Documentation
¶
Overview ¶
Package dynamo holds the account-side authentication stores of plugin/auth in DynamoDB.
plugin/auth owns four framework tables. The ceremony store is authstate/dynamo; the other three are here: the admission allowlist, the passkey credentials, and the issued bootstrap credentials. Importing this package registers all three tables; the client itself belongs to database/dynamo, which these stores read from the request context:
import _ "github.com/shibukawa/popcornweb/database/dynamo" import _ "github.com/shibukawa/popcornweb/authstore/dynamo"
The driver has no TransactWriteItems, so a first passkey enrollment cannot be one unit of work here. CredentialStore fixes an order instead: the bootstrap credential is spent first, then the credential is written, then the account is activated. Every partial outcome of that order is safe, and none of them lets one issued secret enroll two authenticators. See SaveFirstCredential.
Index ¶
- Constants
- func AllowlistTable(name string) dynamodb.TableDefinition
- func BootstrapTable(name string) dynamodb.TableDefinition
- func CredentialTable(name string) dynamodb.TableDefinition
- func Entry(issuer, claim, value, note string) dynamodb.Item
- func EntryKey(issuer, claim, value string) dynamodb.Key
- type Allowlist
- type Bootstrap
- func (Bootstrap) Consume(ctx context.Context, loginID string, at time.Time) error
- func (Bootstrap) Find(ctx context.Context, loginID string) (auth.BootstrapCredential, error)
- func (Bootstrap) Issue(ctx context.Context, credential auth.BootstrapCredential) error
- func (Bootstrap) RecordAttempt(ctx context.Context, loginID string) (int, error)
- type CredentialOptions
- type Credentials
- func (s *Credentials) Delete(ctx context.Context, accountID string, credentialID []byte) error
- func (s *Credentials) Find(ctx context.Context, credentialID []byte) (auth.Credential, error)
- func (s *Credentials) ListByAccount(ctx context.Context, accountID string) ([]auth.Credential, error)
- func (s *Credentials) Save(ctx context.Context, credential auth.Credential, ...) error
- func (s *Credentials) SaveFirstCredential(ctx context.Context, credential auth.Credential, ...) error
- func (s *Credentials) UpdateOnAssertion(ctx context.Context, credentialID []byte, signCount uint32, backupState bool, ...) error
Constants ¶
const ( DeclaredAllowlistTable = "popcornweb_auth_allowlist" DeclaredCredentialTable = "popcornweb_passkey_credential" DeclaredBootstrapTable = "popcornweb_auth_bootstrap" )
Declared table names. They are the names plugin/auth already owns; a deployment maps them onto its own through middleware.dynamo.
Variables ¶
This section is empty.
Functions ¶
func AllowlistTable ¶
func AllowlistTable(name string) dynamodb.TableDefinition
AllowlistTable is the definition of the admission allowlist table.
The partition key holds the issuer, the claim name, and the value joined, rather than the issuer alone with the claim and value as a sort key. A deployment usually has one issuer, so that shape would put every login's admission read on one partition. What it gives up is an issuer-scoped listing, which an administrator answers with a Scan: the table is bounded by how many identities an operator registered, and listing them is an administrative operation rather than a per-request one.
func BootstrapTable ¶
func BootstrapTable(name string) dynamodb.TableDefinition
BootstrapTable is the definition of the issued bootstrap credential table.
A redemption starts from the login ID an operator handed out, so that is the partition key and there is no second question to index for. expires_at is the attribute a deployment points TTL at; nothing here enables or verifies it, and a table without it retains every spent credential forever.
func CredentialTable ¶
func CredentialTable(name string) dynamodb.TableDefinition
CredentialTable is the definition of the passkey credential table.
A login resolves a credential ID, so that is the partition key. Listing an account's credentials is the opposite question, which a global secondary index on the account answers. The index is declared here because the driver has no UpdateTable: an index missing at creation can never be added, so a table created before this definition existed has to be recreated.
Types ¶
type Allowlist ¶
type Allowlist struct{}
Allowlist reads the pre-registration entries an operator provisioned. It writes nothing: provisioning is administrator tooling.
func NewAllowlist ¶
func NewAllowlist() Allowlist
NewAllowlist builds the store. It opens nothing: the client comes from the request context, installed by the database/dynamo middleware.
func (Allowlist) Registered ¶
func (Allowlist) Registered(ctx context.Context, issuer string, candidates []auth.AllowlistCandidate) (bool, error)
Registered answers the whole question in one BatchGetItem, so a login costs one round trip however many claims a deployment compares. Any returned item is a match.
type Bootstrap ¶
type Bootstrap struct{}
Bootstrap is the DynamoDB store of issued bootstrap credentials.
func NewBootstrap ¶
func NewBootstrap() Bootstrap
NewBootstrap builds the store. It opens nothing: the client comes from the request context, installed by the database/dynamo middleware.
func (Bootstrap) Consume ¶
Consume marks the credential spent. It is step one of the registration sequence, so the condition is what makes that sequence single-use: a second redemption of one issued secret fails here, before any credential is written.
func (Bootstrap) Find ¶
Find returns an unconsumed credential.
An unknown login ID and a consumed one return the same error, so a caller cannot tell them apart and enumerate accounts. The read is consistent, because a credential issued moments ago must be redeemable immediately.
func (Bootstrap) Issue ¶
Issue records a new credential. The condition refuses a login ID that is already live rather than overwriting it, so re-issuing to the same ID cannot silently extend someone else's window.
func (Bootstrap) RecordAttempt ¶
RecordAttempt spends one attempt and reports what is left.
It is one request. The contract requires that two parallel guesses cannot both spend the last attempt, and a read followed by a write cannot promise that: both readers would see the same budget and both would decide they had one. ADD applies the decrement on the server, and the condition makes it conditional on there being something to spend.
type CredentialOptions ¶
CredentialOptions configures a credential store.
type Credentials ¶
type Credentials struct {
// contains filtered or unexported fields
}
Credentials is the DynamoDB passkey credential store.
func NewCredentials ¶
func NewCredentials(options CredentialOptions) *Credentials
NewCredentials builds the store. It opens nothing: the client comes from the request context, installed by the database/dynamo middleware.
func (*Credentials) Delete ¶
Delete removes one credential of an account. The condition keeps the account check the relational statement makes in its WHERE clause, so one account cannot delete another's credential by ID.
func (*Credentials) Find ¶
func (s *Credentials) Find(ctx context.Context, credentialID []byte) (auth.Credential, error)
Find reads one credential by ID, consistently: a credential enrolled moments ago must be findable on the next login, and an eventually consistent read would make that a coin flip.
func (*Credentials) ListByAccount ¶
func (s *Credentials) ListByAccount(ctx context.Context, accountID string) ([]auth.Credential, error)
ListByAccount supplies excludeCredentials and allowCredentials, through the account index.
func (*Credentials) Save ¶
func (s *Credentials) Save(ctx context.Context, credential auth.Credential, within func(context.Context) error) error
Save persists a new credential.
The condition makes it an insert: a retried request that already stored the credential is a conditional-check failure rather than a second credential.
A non-nil within runs before the write rather than after it. The framework uses SaveFirstCredential for the enrollment that needs a sequence, so this path exists for a caller that bundles its own; running the callback first keeps the one invariant that matters either way, which is that no credential is stored while the bootstrap credential authorizing it is still unspent.
func (*Credentials) SaveFirstCredential ¶
func (s *Credentials) SaveFirstCredential(ctx context.Context, credential auth.Credential, spend, activate func(context.Context) error) error
SaveFirstCredential applies a passkey-only registration in the order every partial outcome of which is safe.
Spending the bootstrap credential first makes the whole sequence single-use: a credential written before it could be written twice by two parallel redemptions of one issued secret. The reachable interruptions are therefore "bootstrap spent, no credential, account still provisional" and "bootstrap spent, credential stored, account still provisional". Neither can create a session, because a provisional account cannot, and both are resolved by an administrator issuing a new bootstrap credential.
Nothing is rolled back after a failure. A compensating delete that itself failed would leave a state nobody specified, which is worse than a state the documentation names.
func (*Credentials) UpdateOnAssertion ¶
func (s *Credentials) UpdateOnAssertion(ctx context.Context, credentialID []byte, signCount uint32, backupState bool, usedAt time.Time) error
UpdateOnAssertion persists the accepted counter and backup state.
The condition requires the stored counter to be below the accepted one. A counter that does not move forward is a replayed or cloned authenticator, so the store refuses it rather than leaving the caller to notice. A zero stored counter means the authenticator does not keep one, which the condition tolerates by comparing only when the incoming count is above zero.