gatetoken

Documentation

Overview

Package gatetoken issues and authenticates the per-session bearer tokens a session's egress gate presents to the controlplane's internal gate-config endpoint (docs/plan/12_vaults-credentials.md slice 4). Only the hash is stored (the internal/api environment-key precedent); a token is valid for its session's life, so it is minted once when the gate is created and never rotated on the wall clock — a controlplane outage longer than a TTL therefore cannot be misread as a revocation.

Index

• Constants
• func Authenticate(ctx context.Context, pool *pgxpool.Pool, token string) (string, error)
• func Ensure(ctx context.Context, pool *pgxpool.Pool, sessionID, token string) error
• func Mint() string
• func Revoke(ctx context.Context, pool *pgxpool.Pool, sessionID string) error

Constants

const TokenPrefix = "gtk_"

TokenPrefix marks a session-gate token value. Internal-only (never on the /v1 wire), like the apikey_/envkey_ credential values — deliberately NOT in domain/id.go knownPrefixes. The gtk_ prefix makes a leaked token secret-scanner-recognizable.

Functions

func Authenticate

func Authenticate(ctx context.Context, pool *pgxpool.Pool, token string) (string, error)

Authenticate resolves a gate token to the session it is scoped to, or "" if the token is unknown, revoked, or its session has been archived (fail-closed: an archived session's gate must stop being served). There is no wall-clock expiry — validity is the session's lifetime. A deleted session's token is cascade-removed and resolves to "" with no error.

func Ensure

func Ensure(ctx context.Context, pool *pgxpool.Pool, sessionID, token string) error

Ensure makes token the one live gate token for sessionID: in one transaction it revokes every prior unrevoked token for the session and inserts the new hash. Re-minting on a replacement gate therefore invalidates the predecessor (revoke-on-re-mint), and the partial unique index keeps at most one live token per session. Only the hash is stored.

func Mint

func Mint() string

Mint returns a fresh opaque token value. It panics only if the system CSPRNG fails, which is unrecoverable for a server that must mint credentials.

func Revoke

func Revoke(ctx context.Context, pool *pgxpool.Pool, sessionID string) error

Revoke marks sessionID's live gate token revoked without minting a successor — the gated→ungated teardown, where a provision dismantles the session's gate for good and Ensure's revoke-on-re-mint will never run (#197). Idempotent: a session with no live token is a no-op, so a provider that revokes before tearing the pair down can safely retry both if the teardown fails partway.