@c9up/visa 0.1.0 → 0.1.1

package/dist/configure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,UAAU,QAAQ;IACjB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,CACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACjD,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/C;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAUjE"}
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAgBH,UAAU,QAAQ;IACjB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,CACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACjD,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/C;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBjE"}

package/dist/configure.js

@@ -10,8 +10,23 @@
  * in a way that only shows up in production: a memory store loses every
  * session on deploy, and a consent screen nobody wrote grants silently.
  */
+import { access, constants } from "node:fs/promises";
+import { resolve } from "node:path";
 import { stubsRoot } from "./stubs.js";
+/**
+ * The migration this package ships.
+ *
+ * A high, stable prefix rather than a timestamp: these five tables reference
+ * nothing else, so running them last is fine, and a number nobody's own
+ * migrations are likely to have taken means the file lands instead of silently
+ * losing to a name that already exists.
+ */
+const MIGRATION_STUB = "database/migrations/9000_create_visa_tables.stub";
 export async function configure(codemods) {
+    // Fail fast BEFORE touching the project: a pruned tarball or an unreadable
+    // stub must not leave an application with a provider registered, a config
+    // written and no tables to put anything in.
+    await access(resolve(stubsRoot, MIGRATION_STUB), constants.R_OK);
     // The config below reads this, so it is declared here. Writing the file
     // without it leaves an application whose config asks the environment for
     // something nothing ever put there.
@@ -20,5 +35,9 @@ export async function configure(codemods) {
     });
     await codemods.addProvider("@c9up/visa/provider");
     await codemods.makeUsingStub(stubsRoot, "config/visa.stub");
+    // The tables the atlas store reads and writes. An application on another
+    // data layer deletes the file and keeps its own store — which is why this
+    // is a migration and not a schema the package owns.
+    await codemods.makeUsingStub(stubsRoot, MIGRATION_STUB);
 }
 //# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAkBvC,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IACjD,wEAAwE;IACxE,yEAAyE;IACzE,oCAAoC;IACpC,MAAM,QAAQ,CAAC,UAAU,CAAC;QACzB,WAAW,EAAE,uBAAuB;KACpC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAClD,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,kDAAkD,CAAC;AAkB1E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IACjD,2EAA2E;IAC3E,0EAA0E;IAC1E,4CAA4C;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAEjE,wEAAwE;IACxE,yEAAyE;IACzE,oCAAoC;IACpC,MAAM,QAAQ,CAAC,UAAU,CAAC;QACzB,WAAW,EAAE,uBAAuB;KACpC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAClD,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IAC5D,yEAAyE;IACzE,0EAA0E;IAC1E,oDAAoD;IACpD,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACzD,CAAC"}

package/dist/guard.d.ts

@@ -0,0 +1,222 @@
+/**
+ * `visaGuard()` — authenticating a request with an OAuth access token.
+ *
+ * Declared in `config/auth.ts` beside `jwtGuard` and `sessionGuard`, and it
+ * behaves like the access-tokens guard upstream: the authenticated user carries
+ * a `currentAccessToken` whose `abilities` are the token's scopes, with
+ * `allows`, `denies`, `authorize`, `isExpired()` and `lastUsedAt` answering
+ * exactly as they do there. `allows` treats `*` as every ability, which is the
+ * upstream rule read off `@adonisjs/auth`'s build rather than recalled.
+ *
+ * Two things this fixes for every application at once. A route gate no longer
+ * has to introspect the token itself — the scopes are on the guard's token. And
+ * the user is fetched through the application's own provider on every request,
+ * so an account disabled after the token was issued is refused here instead of
+ * in each application that remembers to check.
+ *
+ * NO import of warden. A guard is structurally `{ name, authenticate, verify }`
+ * and that is all warden asks for, so visa stays a package you can run without
+ * it — the same rule every other package in this universe follows.
+ */
+import type { VisaStore } from "./store.js";
+/**
+ * The user shape a guard hands back.
+ *
+ * `id` and the two optional arrays are what warden reads; everything else the
+ * application's provider returns travels with it untouched.
+ */
+export interface GuardUser {
+    id: string;
+    roles?: string[];
+    permissions?: string[];
+    /** The token this request was authenticated with. Set by the guard. */
+    currentAccessToken?: VisaAccessToken;
+    [key: string]: unknown;
+}
+/**
+ * What the guard needs from the store, and nothing more.
+ *
+ * A narrow slice rather than the whole contract: authenticating reads one row
+ * and records one use, so that is what it asks for. A full {@link VisaStore}
+ * satisfies it, and a resource server that keeps only tokens can implement two
+ * methods instead of twelve.
+ */
+export type GuardStore = Pick<VisaStore, "findAccessToken" | "touchAccessToken" | "saveAccessToken" | "revokeAccessToken">;
+/** What a guard answers. Warden's `AuthResult`, declared here so visa owes it nothing. */
+export interface GuardResult {
+    authenticated: boolean;
+    user?: GuardUser;
+    error?: string;
+}
+/** What a test client sends to be this user. Warden's `AuthClientResponse`. */
+export interface GuardClientResponse {
+    headers?: Record<string, string>;
+    session?: Record<string, unknown>;
+}
+/**
+ * The token behind the current request.
+ *
+ * Upstream's `AccessToken`, minus what an opaque OAuth token has no equivalent
+ * for: there is no `identifier`/`secret` pair to decode here, because visa
+ * stores a hash and the plaintext never comes back.
+ */
+export declare class VisaAccessToken {
+    /** The client the token was issued to — an OAuth token always has one. */
+    readonly clientId: string;
+    /** Absent for `client_credentials`: there is no user behind it. */
+    readonly userId?: string;
+    /** The token's scopes. Named `abilities` for the upstream surface. */
+    readonly abilities: string[];
+    /**
+     * A recognisable name, as upstream carries one.
+     *
+     * An OAuth token is not named by the user who holds it — it is named by the
+     * client it was issued to — so this is the client's name when the store
+     * knows it, and null otherwise.
+     */
+    readonly name: string | null;
+    readonly expiresAt: Date | null;
+    readonly lastUsedAt: Date | null;
+    /**
+     * The token itself, and only just after it was created.
+     *
+     * Upstream's `value`: the one moment the plaintext exists is when it is
+     * minted, because what is stored is a hash. A token read back from the
+     * store never has it, and that is not a gap — it is why a database copy is
+     * not a set of working tokens.
+     */
+    readonly value?: string;
+    constructor(attributes: {
+        clientId: string;
+        userId?: string;
+        abilities: string[];
+        name?: string | null;
+        expiresAt?: Date | null;
+        lastUsedAt?: Date | null;
+        value?: string;
+    });
+    /** `*` means every ability — upstream's rule, read off its build. */
+    allows(ability: string): boolean;
+    denies(ability: string): boolean;
+    /**
+     * Throw unless the token carries `ability`.
+     *
+     * The upstream error id verbatim, so a handler that already maps
+     * `E_UNAUTHORIZED_ACCESS` keeps working.
+     */
+    authorize(ability: string): void;
+    /** A token with no expiry never expires. */
+    isExpired(): boolean;
+    /** Upstream's keys, plus the client an OAuth token always belongs to. */
+    toJSON(): {
+        type: "bearer";
+        name: string | null;
+        token: string | undefined;
+        clientId: string;
+        abilities: string[];
+        lastUsedAt: Date | null;
+        expiresAt: Date | null;
+    };
+}
+export interface VisaGuardConfig {
+    /**
+     * Where the tokens live. A function, so the guard can be built in
+     * `config/auth.ts` before the provider has seated the manager — config is
+     * read at boot, and the store exists a moment later.
+     */
+    store: GuardStore | (() => GuardStore);
+    /**
+     * The application's user provider — upstream's `tokensUserProvider({ model })`.
+     *
+     * Called on every authenticated request, deliberately: a token issued to an
+     * account that has since been disabled must stop working, and the only way
+     * to know is to ask. Answer `null` and the request is refused.
+     */
+    findUser: (userId: string) => Promise<GuardUser | null>;
+    /**
+     * What a `client_credentials` token authenticates as, when anything.
+     *
+     * There is no user behind that grant, so by default such a token does not
+     * authenticate a user at all and the guard refuses. An application that
+     * serves machine callers supplies this and gets a subject of its choosing.
+     */
+    findClientSubject?: (clientId: string) => Promise<GuardUser | null>;
+    /** Guard name, for `auth.use(name)`. Defaults to `visa`. */
+    name?: string;
+    /**
+     * The client a token minted by {@link VisaGuard.createToken} belongs to.
+     *
+     * Upstream's guard needs no such thing because it has no clients. Here
+     * every token is issued TO somebody, and one with no client could not be
+     * introspected, revoked by its owner, or listed on a "connected
+     * applications" screen. Name the first-party application and a minted
+     * token is an ordinary token in every other respect.
+     */
+    tokenClientId?: string;
+    /** How long a minted token lasts — upstream's `expiresIn`, in seconds. */
+    expiresInSeconds?: number;
+}
+/**
+ * A guard, in the shape warden's config expects.
+ *
+ * Shared per application, so it holds no per-request state — the same rule
+ * warden states for its own strategies.
+ */
+export declare class VisaGuard {
+    #private;
+    readonly name: string;
+    constructor(config: VisaGuardConfig);
+    /**
+     * There is no password flow here, and OAuth 2.1 removed the one there used
+     * to be. A token comes from the token endpoint.
+     *
+     * THROWS rather than answering "not authenticated", which is what warden's
+     * own access-tokens guard does: a bearer guard handed an email and a
+     * password is a misconfigured application, not a bad credential, and the two
+     * must not produce the same 401.
+     */
+    authenticate(): Promise<GuardResult>;
+    /**
+     * Mint a token for `user`, as upstream's guard does.
+     *
+     * The token is a real one: stored hashed, listed, introspectable,
+     * revocable. What it skips is the authorization code flow, so it is for a
+     * FIRST-PARTY client you own — `tokenClientId` — and nothing here should
+     * ever be handed a third-party client id.
+     */
+    createToken(user: {
+        id: string;
+    } | string, abilities?: string[], options?: {
+        name?: string;
+        expiresInSeconds?: number;
+    }): Promise<VisaAccessToken>;
+    /**
+     * Revoke a token — upstream's `invalidateToken`.
+     *
+     * NAMED DEVIATION — upstream's guard is built per request and invalidates
+     * the token it just authenticated with, so it takes no argument. A warden
+     * strategy is shared by the whole application and holds no per-request
+     * state, by warden's own rule, so the token to revoke is passed in. A
+     * sign-out handler has it: it is the bearer credential of the request.
+     *
+     * Answers whether the token was there to revoke.
+     */
+    invalidateToken(presented: string): Promise<boolean>;
+    /**
+     * What a test client sends to be `user` — upstream's signature.
+     *
+     * It mints a token, as upstream does, so a test authenticates the way the
+     * application will rather than against a credential the store has never
+     * seen.
+     */
+    authenticateAsClient(user: {
+        id: string;
+    } | string, abilities?: string[], options?: {
+        name?: string;
+        expiresInSeconds?: number;
+    }): Promise<GuardClientResponse>;
+    verify(presented: string): Promise<GuardResult>;
+}
+/** Build a visa guard from its config — `visaGuard({...})` in `config/auth.ts`. */
+export declare function visaGuard(config: VisaGuardConfig): VisaGuard;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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"}

package/dist/guard.js

@@ -0,0 +1,274 @@
+/**
+ * `visaGuard()` — authenticating a request with an OAuth access token.
+ *
+ * Declared in `config/auth.ts` beside `jwtGuard` and `sessionGuard`, and it
+ * behaves like the access-tokens guard upstream: the authenticated user carries
+ * a `currentAccessToken` whose `abilities` are the token's scopes, with
+ * `allows`, `denies`, `authorize`, `isExpired()` and `lastUsedAt` answering
+ * exactly as they do there. `allows` treats `*` as every ability, which is the
+ * upstream rule read off `@adonisjs/auth`'s build rather than recalled.
+ *
+ * Two things this fixes for every application at once. A route gate no longer
+ * has to introspect the token itself — the scopes are on the guard's token. And
+ * the user is fetched through the application's own provider on every request,
+ * so an account disabled after the token was issued is refused here instead of
+ * in each application that remembers to check.
+ *
+ * NO import of warden. A guard is structurally `{ name, authenticate, verify }`
+ * and that is all warden asks for, so visa stays a package you can run without
+ * it — the same rule every other package in this universe follows.
+ */
+import { hashSecret, randomToken } from "./crypto.js";
+import { verifyAccessToken } from "./introspect.js";
+/**
+ * The token behind the current request.
+ *
+ * Upstream's `AccessToken`, minus what an opaque OAuth token has no equivalent
+ * for: there is no `identifier`/`secret` pair to decode here, because visa
+ * stores a hash and the plaintext never comes back.
+ */
+export class VisaAccessToken {
+    /** The client the token was issued to — an OAuth token always has one. */
+    clientId;
+    /** Absent for `client_credentials`: there is no user behind it. */
+    userId;
+    /** The token's scopes. Named `abilities` for the upstream surface. */
+    abilities;
+    /**
+     * A recognisable name, as upstream carries one.
+     *
+     * An OAuth token is not named by the user who holds it — it is named by the
+     * client it was issued to — so this is the client's name when the store
+     * knows it, and null otherwise.
+     */
+    name;
+    expiresAt;
+    lastUsedAt;
+    /**
+     * The token itself, and only just after it was created.
+     *
+     * Upstream's `value`: the one moment the plaintext exists is when it is
+     * minted, because what is stored is a hash. A token read back from the
+     * store never has it, and that is not a gap — it is why a database copy is
+     * not a set of working tokens.
+     */
+    value;
+    constructor(attributes) {
+        this.clientId = attributes.clientId;
+        if (attributes.userId !== undefined)
+            this.userId = attributes.userId;
+        this.abilities = [...attributes.abilities];
+        this.name = attributes.name ?? null;
+        this.expiresAt = attributes.expiresAt ?? null;
+        this.lastUsedAt = attributes.lastUsedAt ?? null;
+        if (attributes.value !== undefined)
+            this.value = attributes.value;
+    }
+    /** `*` means every ability — upstream's rule, read off its build. */
+    allows(ability) {
+        return this.abilities.includes(ability) || this.abilities.includes("*");
+    }
+    denies(ability) {
+        return !this.allows(ability);
+    }
+    /**
+     * Throw unless the token carries `ability`.
+     *
+     * The upstream error id verbatim, so a handler that already maps
+     * `E_UNAUTHORIZED_ACCESS` keeps working.
+     */
+    authorize(ability) {
+        if (this.allows(ability))
+            return;
+        const error = new Error(`Access denied: the token does not carry "${ability}"`);
+        error.code = "E_UNAUTHORIZED_ACCESS";
+        error.status = 403;
+        throw error;
+    }
+    /** A token with no expiry never expires. */
+    isExpired() {
+        if (this.expiresAt === null)
+            return false;
+        return this.expiresAt.getTime() <= Date.now();
+    }
+    /** Upstream's keys, plus the client an OAuth token always belongs to. */
+    toJSON() {
+        return {
+            type: "bearer",
+            name: this.name,
+            // Present exactly once, on the token `createToken` just returned —
+            // which is the only time a caller can hand it to anybody.
+            token: this.value,
+            clientId: this.clientId,
+            abilities: this.abilities,
+            lastUsedAt: this.lastUsedAt,
+            expiresAt: this.expiresAt,
+        };
+    }
+}
+/** An hour, as the token endpoint uses by default. */
+const DEFAULT_TTL = 3600;
+/**
+ * A guard, in the shape warden's config expects.
+ *
+ * Shared per application, so it holds no per-request state — the same rule
+ * warden states for its own strategies.
+ */
+export class VisaGuard {
+    name;
+    #config;
+    constructor(config) {
+        this.#config = config;
+        this.name = config.name ?? "visa";
+    }
+    #store() {
+        const store = this.#config.store;
+        return typeof store === "function" ? store() : store;
+    }
+    /**
+     * There is no password flow here, and OAuth 2.1 removed the one there used
+     * to be. A token comes from the token endpoint.
+     *
+     * THROWS rather than answering "not authenticated", which is what warden's
+     * own access-tokens guard does: a bearer guard handed an email and a
+     * password is a misconfigured application, not a bad credential, and the two
+     * must not produce the same 401.
+     */
+    async authenticate() {
+        throw new Error("visa authenticates a bearer token, not credentials. Use verify() with the access token.");
+    }
+    /**
+     * Mint a token for `user`, as upstream's guard does.
+     *
+     * The token is a real one: stored hashed, listed, introspectable,
+     * revocable. What it skips is the authorization code flow, so it is for a
+     * FIRST-PARTY client you own — `tokenClientId` — and nothing here should
+     * ever be handed a third-party client id.
+     */
+    async createToken(user, abilities = ["*"], options = {}) {
+        const clientId = this.#config.tokenClientId;
+        if (clientId === undefined) {
+            throw new Error("[visa] createToken needs `tokenClientId` — a token is always issued to a client. Name the first-party application in visaGuard({ tokenClientId }).");
+        }
+        const userId = typeof user === "string" ? user : user.id;
+        const ttl = options.expiresInSeconds ?? this.#config.expiresInSeconds ?? DEFAULT_TTL;
+        const secret = randomToken();
+        const expiresAt = new Date(Date.now() + ttl * 1000);
+        await this.#store().saveAccessToken({
+            tokenHash: hashSecret(secret),
+            clientId,
+            userId,
+            scopes: abilities,
+            expiresAt,
+        });
+        return new VisaAccessToken({
+            clientId,
+            userId,
+            abilities,
+            name: options.name ?? null,
+            expiresAt,
+            // The one moment the plaintext exists.
+            value: secret,
+        });
+    }
+    /**
+     * Revoke a token — upstream's `invalidateToken`.
+     *
+     * NAMED DEVIATION — upstream's guard is built per request and invalidates
+     * the token it just authenticated with, so it takes no argument. A warden
+     * strategy is shared by the whole application and holds no per-request
+     * state, by warden's own rule, so the token to revoke is passed in. A
+     * sign-out handler has it: it is the bearer credential of the request.
+     *
+     * Answers whether the token was there to revoke.
+     */
+    async invalidateToken(presented) {
+        const store = this.#store();
+        const hash = hashSecret(presented);
+        const existing = await store.findAccessToken(hash);
+        if (existing === null || existing.revokedAt !== undefined)
+            return false;
+        await store.revokeAccessToken(hash, new Date());
+        return true;
+    }
+    /**
+     * What a test client sends to be `user` — upstream's signature.
+     *
+     * It mints a token, as upstream does, so a test authenticates the way the
+     * application will rather than against a credential the store has never
+     * seen.
+     */
+    async authenticateAsClient(user, abilities = ["*"], options = {}) {
+        const token = await this.createToken(user, abilities, options);
+        return { headers: { authorization: `Bearer ${token.value}` } };
+    }
+    async verify(presented) {
+        const store = this.#store();
+        const now = new Date();
+        const verified = await verifyAccessToken(presented, store, now);
+        if (verified === null) {
+            return { authenticated: false, error: "Invalid or expired access token" };
+        }
+        const subject = verified.userId === undefined
+            ? await this.#config.findClientSubject?.(verified.clientId)
+            : await this.#config.findUser(verified.userId);
+        if (subject === null || subject === undefined) {
+            // The account is gone or disabled since the token was minted. Refusing
+            // here is the point of asking on every request.
+            return {
+                authenticated: false,
+                error: verified.userId === undefined
+                    ? "This token authenticates no user"
+                    : "The account behind this token is no longer available",
+            };
+        }
+        // The PREVIOUS use is what the token reports, and this one is recorded
+        // after — the same order upstream reads its row in.
+        await touch(store, presented, now);
+        const token = new VisaAccessToken({
+            clientId: verified.clientId,
+            ...(verified.userId === undefined ? {} : { userId: verified.userId }),
+            abilities: verified.scopes,
+            expiresAt: verified.expiresAt ?? null,
+            lastUsedAt: verified.lastUsedAt ?? null,
+        });
+        // A copy: the provider's object is the application's, and a guard that
+        // mutated it would leak one request's token into the next.
+        const user = { ...subject, currentAccessToken: token };
+        if (verified.scopes.length > 0) {
+            // Scopes surface on `permissions` as well, the way warden's access-token
+            // guard does it, so `ctx.auth.user.permissions` reads the same whichever
+            // guard authenticated.
+            //
+            // They remain a SEPARATE axis from the route-level rights gate, exactly
+            // as upstream: a token ability is checked with
+            // `currentAccessToken.allows(...)`, and Bouncer does not consult it.
+            user.permissions = [
+                ...new Set([...(subject.permissions ?? []), ...verified.scopes]),
+            ];
+        }
+        return { authenticated: true, user };
+    }
+}
+/**
+ * Record that the token was just used.
+ *
+ * Never fatal: a store with no `touchAccessToken` — the contract shipped
+ * without one — still authenticates, it simply reports no last use.
+ */
+async function touch(store, presented, now) {
+    if (store.touchAccessToken === undefined)
+        return;
+    try {
+        await store.touchAccessToken(hashSecret(presented), now);
+    }
+    catch {
+        // Recording the use is bookkeeping; failing it must not refuse a request
+        // whose token is valid.
+    }
+}
+/** Build a visa guard from its config — `visaGuard({...})` in `config/auth.ts`. */
+export function visaGuard(config) {
+    return new VisaGuard(config);
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -15,9 +15,11 @@ export { assertGrantAllowed, authenticateClient, type ClientCredentials, readCre
 export { defineConfig, type VisaConfigInput } from "./config.js";
 export { hashSecret, randomToken, secretMatches, sha256 } from "./crypto.js";
 export { type AuthorizationErrorCode, OAuthError, type ProtocolErrorCode, type TokenErrorCode, VisaError, } from "./errors.js";
+export { type GuardClientResponse, type GuardResult, type GuardStore, type GuardUser, VisaAccessToken, VisaGuard, type VisaGuardConfig, visaGuard, } from "./guard.js";
 export { introspect, revoke, verifyAccessToken } from "./introspect.js";
 export { clearVisa, default as visa, getVisa, setVisa, } from "./services/main.js";
 export type { VisaStore } from "./store.js";
+export { type AtlasDb, type AtlasQuery, AtlasStore, type AtlasStoreTables, } from "./stores/atlas.js";
 export { MemoryStore } from "./stores/memory.js";
 export { type TokenOptions, type TokenRequest, token } from "./token.js";
 export type { AccessToken, AuthorizationCode, Client, ClientAuthMethod, Consent, GrantType, IntrospectionResponse, RefreshToken, TokenResponse, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACN,KAAK,sBAAsB,EAC3B,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,SAAS,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EACN,SAAS,EACT,OAAO,IAAI,IAAI,EACf,OAAO,EACP,OAAO,GACP,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EACX,WAAW,EACX,iBAAiB,EACjB,MAAM,EACN,gBAAgB,EAChB,OAAO,EACP,SAAS,EACT,qBAAqB,EACrB,YAAY,EACZ,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,WAAW,GACX,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACN,KAAK,sBAAsB,EAC3B,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,SAAS,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,eAAe,EACf,SAAS,EACT,KAAK,eAAe,EACpB,SAAS,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EACN,SAAS,EACT,OAAO,IAAI,IAAI,EACf,OAAO,EACP,OAAO,GACP,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,UAAU,EACV,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EACX,WAAW,EACX,iBAAiB,EACjB,MAAM,EACN,gBAAgB,EAChB,OAAO,EACP,SAAS,EACT,qBAAqB,EACrB,YAAY,EACZ,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,WAAW,GACX,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -15,8 +15,10 @@ export { assertGrantAllowed, authenticateClient, readCredentials, redirectUriMat
 export { defineConfig } from "./config.js";
 export { hashSecret, randomToken, secretMatches, sha256 } from "./crypto.js";
 export { OAuthError, VisaError, } from "./errors.js";
+export { VisaAccessToken, VisaGuard, visaGuard, } from "./guard.js";
 export { introspect, revoke, verifyAccessToken } from "./introspect.js";
 export { clearVisa, default as visa, getVisa, setVisa, } from "./services/main.js";
+export { AtlasStore, } from "./stores/atlas.js";
 export { MemoryStore } from "./stores/memory.js";
 export { token } from "./token.js";
 export { VisaManager, } from "./VisaManager.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAGN,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EAEnB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAElB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAwB,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAEN,UAAU,EAGV,SAAS,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EACN,SAAS,EACT,OAAO,IAAI,IAAI,EACf,OAAO,EACP,OAAO,GACP,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAwC,KAAK,EAAE,MAAM,YAAY,CAAC;AAYzE,OAAO,EAGN,WAAW,GACX,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAGN,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EAEnB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,kBAAkB,EAClB,kBAAkB,EAElB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAwB,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAEN,UAAU,EAGV,SAAS,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAKN,eAAe,EACf,SAAS,EAET,SAAS,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EACN,SAAS,EACT,OAAO,IAAI,IAAI,EACf,OAAO,EACP,OAAO,GACP,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGN,UAAU,GAEV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAwC,KAAK,EAAE,MAAM,YAAY,CAAC;AAYzE,OAAO,EAGN,WAAW,GACX,MAAM,kBAAkB,CAAC"}

package/dist/introspect.d.ts

@@ -24,9 +24,11 @@ export declare function revoke(request: Record<string, unknown>, credentials: Cl
  * What a resource server calls on every request — so it reads the store
  * directly instead of going through introspection's client authentication.
  */
-export declare function verifyAccessToken(presented: string, store: VisaStore, now?: Date): Promise<{
+export declare function verifyAccessToken(presented: string, store: Pick<VisaStore, "findAccessToken">, now?: Date): Promise<{
     clientId: string;
     userId?: string;
     scopes: string[];
+    expiresAt: Date;
+    lastUsedAt?: Date;
 } | null>;
 //# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAG1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKxD,wBAAsB,UAAU,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,EACtB,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CAsDhC;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,GACpB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CASzE"}
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAG1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKxD,wBAAsB,UAAU,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,EACtB,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CAsDhC;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,iBAAiB,EAC9B,KAAK,EAAE,SAAS,EAChB,GAAG,GAAE,IAAiB,GACpB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACtC,SAAS,EAAE,MAAM,EAGjB,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EACzC,GAAG,GAAE,IAAiB,GACpB,OAAO,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,CAAC,EAAE,IAAI,CAAC;CAClB,GAAG,IAAI,CAAC,CAeR"}

package/dist/introspect.js

@@ -92,7 +92,10 @@ export async function revoke(request, credentials, store, now = new Date()) {
  * What a resource server calls on every request — so it reads the store
  * directly instead of going through introspection's client authentication.
  */
-export async function verifyAccessToken(presented, store, now = new Date()) {
+export async function verifyAccessToken(presented, 
+// Only the one read: a resource server that keeps nothing but tokens should
+// not have to implement eleven methods it never calls.
+store, now = new Date()) {
     const token = await store.findAccessToken(hashSecret(presented));
     if (token === null)
         return null;
@@ -102,6 +105,12 @@ export async function verifyAccessToken(presented, store, now = new Date()) {
         clientId: token.clientId,
         ...(token.userId === undefined ? {} : { userId: token.userId }),
         scopes: token.scopes,
+        // Carried out so a caller can report the expiry it just checked, rather
+        // than reading the store a second time to say the same thing.
+        expiresAt: token.expiresAt,
+        // The PREVIOUS use, before this one is recorded — which is what the
+        // upstream guard shows on `currentAccessToken.lastUsedAt`.
+        ...(token.lastUsedAt === undefined ? {} : { lastUsedAt: token.lastUsedAt }),
     };
 }
 function asString(value) {