@udibo/oauth2 0.1.0

package/esm/server/resource-server.js

@@ -0,0 +1,365 @@
+/**
+ * Resource Server implementation for protecting resources with OAuth2 tokens.
+ *
+ * Implements bearer token validation per RFC 6750.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import { BasicScope } from "../models/scope.js";
+import { AccessDeniedError, InsufficientPermissionsError, InsufficientScopeError, InvalidTokenError, toOAuth2Error, } from "../errors.js";
+import { authorizationFromClaims, } from "../models/authorization.js";
+/** Bearer token regex pattern. */
+export const BEARER_TOKEN = /^ *(?:[Bb][Ee][Aa][Rr][Ee][Rr]) +([\w-.~+/]+=*) *$/;
+const FAILURE_LABELS = {
+    organization: "requires organization",
+    role: "requires role",
+    orgRole: "requires organization role",
+    permission: "requires permission",
+};
+const CHALLENGE_ERROR_CODES = new Set([
+    "invalid_request",
+    "invalid_token",
+    "insufficient_scope",
+]);
+/**
+ * Validates OAuth2 bearer access tokens (RFC 6750) so API endpoints can require
+ * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
+ * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
+ *
+ * A single instance serves every tenant/origin; per-request services come from
+ * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
+ * single-tenant server, `resolve` is a constant function returning the same
+ * services every time.
+ *
+ * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
+ * ({@linkcode AccessDeniedError} when no token is sent,
+ * {@linkcode InvalidTokenError} for an invalid/expired token, and
+ * {@linkcode InsufficientScopeError} when scope is lacking); use
+ * {@linkcode handleAuthError} to turn them into RFC 6750 responses.
+ *
+ * @template Client The client entity type.
+ * @template User The resource-owner entity type.
+ * @template S The scope type used for granted/required scope comparisons.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import type { ClientInterface, TokenReaderInterface } from "@udibo/oauth2/server";
+ * import { ResourceServer } from "@udibo/oauth2/server/resource";
+ *
+ * interface User { id: string }
+ *
+ * declare const app: Hono;
+ * declare const tokenService: TokenReaderInterface<ClientInterface, User>;
+ *
+ * const server = new ResourceServer({
+ *   resolve: () => ({ services: { tokenService } }),
+ * });
+ *
+ * app.get("/api/me", async (c) => {
+ *   try {
+ *     const { user } = await server.authenticate(c.req.raw, "identity:read");
+ *     return c.json(user ?? null);
+ *   } catch (error) {
+ *     return server.handleAuthError(error);
+ *   }
+ * });
+ * ```
+ */
+export class ResourceServer {
+    /** Scope constructor used to parse and compare scopes. */
+    Scope;
+    /** Protection space named in `WWW-Authenticate` challenges. */
+    realm;
+    /** Leeway in seconds applied to the access token's expiry. Defaults to `0`. */
+    clockSkewSeconds;
+    /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
+    errorFormat;
+    /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
+    throwOnError;
+    /** Resolves the per-request {@link ResourceServerContext}. */
+    resolveContext;
+    /** Creates a resource server from the given {@linkcode ResourceServerOptions}. */
+    constructor(options) {
+        this.Scope = options.Scope ??
+            BasicScope;
+        this.realm = options.realm ?? "Service";
+        this.clockSkewSeconds = options.clockSkewSeconds ?? 0;
+        this.errorFormat = options.errorFormat ?? "oauth2";
+        this.throwOnError = options.throwOnError ?? false;
+        this.resolveContext = options.resolve;
+    }
+    /**
+     * Builds a WWW-Authenticate header value per RFC 6750 Section 3.
+     *
+     * The header includes:
+     * - realm: The protection space
+     * - error: The error code (for 401/403 responses)
+     * - error_description: Human-readable error description
+     * - scope: Required scope (for insufficient_scope errors)
+     *
+     * RFC 6750 Section 3.1 registers exactly three challenge codes —
+     * `invalid_request`, `invalid_token`, `insufficient_scope` — so an error
+     * carrying anything else (including the `access_denied` this server raises
+     * when a request presents no credentials at all, which the same section says
+     * MUST NOT be given a code) produces a bare `realm` challenge. Pick the error
+     * class accordingly: a client reads a coded challenge and acts on it, and
+     * {@linkcode InsufficientScopeError} is the one that tells it "your token is
+     * fine, it just lacks scope" rather than sending it off to refresh.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3
+     */
+    buildWwwAuthenticate(error, requiredScope) {
+        const quote = (value) => 
+        // deno-lint-ignore no-control-regex
+        value.replace(/[\x00-\x1f\x7f]/g, "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const parts = [`realm="${quote(this.realm)}"`];
+        const code = error?.extensions.error;
+        if (error && code && CHALLENGE_ERROR_CODES.has(code)) {
+            parts.push(`error="${quote(code)}"`);
+            if (error.message) {
+                parts.push(`error_description="${quote(error.message)}"`);
+            }
+        }
+        if (requiredScope) {
+            parts.push(`scope="${quote(requiredScope)}"`);
+        }
+        else if (error instanceof InsufficientScopeError) {
+            const scope = error.extensions.requiredScope;
+            if (scope) {
+                parts.push(`scope="${quote(scope)}"`);
+            }
+        }
+        return `Bearer ${parts.join(", ")}`;
+    }
+    /**
+     * Creates an error response for an OAuth2 error.
+     *
+     * The response body is formatted according to {@link errorFormat}:
+     * - `"oauth2"`: `{ error, error_description?, error_uri? }` as JSON.
+     * - `"problem-details"`: RFC 9457 Problem Details with OAuth2 extensions.
+     *
+     * Does **not** set any response headers beyond `Content-Type`. Any extra
+     * response headers (`WWW-Authenticate`, `Cache-Control`, `Pragma`, …) must
+     * be set on the error via its `headers` property before calling this
+     * method; they are copied through verbatim.
+     */
+    createErrorResponse(error) {
+        const oauth2Error = toOAuth2Error(error);
+        const response = this.errorFormat === "problem-details"
+            ? oauth2Error.getResponse()
+            : this.#createOAuth2ErrorResponse(oauth2Error);
+        for (const [key, value] of oauth2Error.headers) {
+            if (key.toLowerCase() === "content-type")
+                continue;
+            response.headers.set(key, value);
+        }
+        return response;
+    }
+    #createOAuth2ErrorResponse(oauth2Error) {
+        const body = {
+            error: oauth2Error.extensions.error ?? "server_error",
+        };
+        const description = oauth2Error.extensions.error_description ??
+            oauth2Error.exposedMessage;
+        if (description) {
+            body.error_description = description;
+        }
+        const errorUri = oauth2Error.extensions.error_uri ?? oauth2Error.type;
+        if (errorUri) {
+            body.error_uri = errorUri;
+        }
+        return new Response(JSON.stringify(body), {
+            status: oauth2Error.status,
+            headers: { "Content-Type": "application/json;charset=UTF-8" },
+        });
+    }
+    /**
+     * Normalizes an error at a handler boundary and either rethrows it (when
+     * {@link throwOnError} is true) or converts it to a response.
+     *
+     * The optional `prepare` callback lets a handler annotate the error —
+     * usually by setting headers like `Cache-Control` or `WWW-Authenticate`
+     * that belong on both the thrown error and the response — before the
+     * throw/respond decision is made.
+     */
+    handleError(error, prepare) {
+        const oauth2Error = toOAuth2Error(error);
+        prepare?.(oauth2Error);
+        if (this.throwOnError)
+            throw oauth2Error;
+        return this.createErrorResponse(oauth2Error);
+    }
+    /**
+     * {@link handleError} variant that automatically attaches a
+     * `WWW-Authenticate` header (per RFC 6750 Section 3) when the error's
+     * status is 401 or 403. Use this at bearer-token boundaries to avoid the
+     * boilerplate of building the header for each error response.
+     *
+     * @example
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { ClientInterface } from "@udibo/oauth2/server";
+     * import { ResourceServer } from "@udibo/oauth2/server/resource";
+     *
+     * interface User { id: string }
+     *
+     * declare const app: Hono;
+     * declare const server: ResourceServer<ClientInterface, User>;
+     *
+     * app.get("/api/me", async (c) => {
+     *   try {
+     *     const ctx = await server.authenticate(c.req.raw);
+     *     return c.json(ctx.user ?? null);
+     *   } catch (error) {
+     *     return server.handleAuthError(error);
+     *   }
+     * });
+     * ```
+     */
+    handleAuthError(error) {
+        return this.handleError(error, (e) => {
+            if (e.status === 401 || e.status === 403) {
+                e.headers.set("WWW-Authenticate", this.buildWwwAuthenticate(e));
+            }
+        });
+    }
+    /**
+     * Extracts an access token from a request.
+     * Looks in the Authorization header (Bearer token) first,
+     * then in the request body for form-encoded requests.
+     */
+    async getAccessToken(request) {
+        const authorization = request.headers.get("authorization");
+        if (authorization) {
+            const match = BEARER_TOKEN.exec(authorization);
+            if (match)
+                return match[1];
+        }
+        const contentType = request.headers.get("content-type");
+        if (request.method === "POST" &&
+            contentType?.includes("application/x-www-form-urlencoded")) {
+            try {
+                const body = await request.clone().formData();
+                const accessToken = body.get("access_token");
+                if (typeof accessToken === "string")
+                    return accessToken;
+            }
+            catch {
+                // ignore
+            }
+        }
+        return null;
+    }
+    /**
+     * Retrieves and validates a token by access token string.
+     *
+     * The token's expiry is compared against now with {@linkcode
+     * clockSkewSeconds} of leeway, so the same tolerance applies whichever
+     * token reader produced the token.
+     *
+     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
+     *   configured leeway, or revoked
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+     */
+    async getToken(accessToken, services) {
+        const { tokenService } = services;
+        const token = await tokenService.getToken(accessToken);
+        if (!token) {
+            throw new InvalidTokenError("invalid access token");
+        }
+        if (token.accessTokenExpiresAt) {
+            const deadline = token.accessTokenExpiresAt.getTime() +
+                this.clockSkewSeconds * 1000;
+            if (deadline < Date.now()) {
+                throw new InvalidTokenError("access token has expired");
+            }
+        }
+        return token;
+    }
+    /**
+     * Authenticates a request and verifies the token has the required scope.
+     *
+     * @param request The incoming request
+     * @param requiredScope Optional scope required to access the resource
+     * @returns The authenticated context with token, client, user, and scope
+     * @throws {AccessDeniedError} If no token is provided
+     * @throws {InvalidTokenError} If the token is invalid or expired
+     * @throws {InsufficientScopeError} If the token lacks required scope (HTTP 403)
+     * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+     */
+    async authenticate(request, requiredScope) {
+        const accessToken = await this.getAccessToken(request);
+        if (!accessToken) {
+            throw new AccessDeniedError("authentication required");
+        }
+        const { services } = await this.resolveContext(request);
+        const token = await this.getToken(accessToken, services);
+        if (requiredScope) {
+            this.assertScope(token.scope, requiredScope);
+        }
+        return {
+            token,
+            client: token.client,
+            user: token.user,
+            scope: token.scope,
+            authorization: authorizationFromClaims(token.claims, token.scope),
+        };
+    }
+    /**
+     * Throws unless the authenticated context satisfies every condition —
+     * the assertion behind the adapters' `require()` middleware, public so a
+     * handler authenticating manually can reuse the same checks.
+     *
+     * Scope conditions go through {@linkcode assertScope}, so their failure is
+     * the same RFC 6750 `insufficient_scope` challenge `requireScope` sends.
+     * Every other condition is answered by the context's
+     * {@linkcode AuthenticatedContext.authorization}; the first unmet one
+     * throws a plain 403 naming the failed check.
+     *
+     * @throws {InsufficientScopeError} If the token lacks a required scope (403,
+     *   `insufficient_scope` challenge).
+     * @throws {InsufficientPermissionsError} If a permission, role, or
+     *   organization condition fails (403, no challenge code).
+     */
+    assertAuthorized(context, conditions) {
+        if (conditions.scope !== undefined) {
+            const required = typeof conditions.scope === "string"
+                ? conditions.scope
+                : conditions.scope.join(" ");
+            this.assertScope(context.scope, required);
+        }
+        const failure = context.authorization.unmet(conditions);
+        if (failure) {
+            const required = failure.required === true
+                ? "an active organization"
+                : failure.required;
+            throw new InsufficientPermissionsError(`${FAILURE_LABELS[failure.kind]}: ${required}`);
+        }
+    }
+    /**
+     * Throws {@link InsufficientScopeError} unless `granted` contains
+     * `requiredScope`. Shared by {@link authenticate} and the adapters'
+     * scope-only guards (`requireScope`) so the comparison and the RFC 6750
+     * error stay identical — a guard that checks an already-authenticated
+     * request's scope (without re-validating the token) calls this with the
+     * context's `scope`. Public so a handler authenticating manually can reuse
+     * the same check.
+     *
+     * @throws {InsufficientScopeError} If `granted` lacks `requiredScope` (403).
+     */
+    assertScope(granted, requiredScope) {
+        const scope = typeof requiredScope === "string"
+            ? new this.Scope(requiredScope)
+            : requiredScope;
+        if (!granted?.has(scope)) {
+            throw new InsufficientScopeError("insufficient scope", {
+                extensions: { requiredScope: scope.toString() },
+            });
+        }
+    }
+}
+export { IntrospectionTokenReader } from "./introspection-token-reader.js";
+export { JwksTokenReader } from "./jwks-token-reader.js";

package/esm/server/services/authorization-code.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Authorization code service interface and abstract implementation.
+ * @module
+ */
+import type { AuthorizationCode } from "../../models/authorization-code.js";
+import type { ClientInterface } from "../../models/client.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { ClientServiceInterface } from "./client.js";
+import type { UserServiceInterface } from "./user.js";
+/**
+ * Service interface for authorization code management.
+ */
+export interface AuthorizationCodeServiceInterface<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> {
+    /** Lifetime of authorization codes in seconds. */
+    lifetime: number;
+    /** Generates an authorization code string. */
+    generateCode(client: Client, user: User, scope?: Scope | null): Promise<string>;
+    /** Gets the date that a new authorization code would expire at. */
+    expiresAt(client: Client, user: User, scope?: Scope | null): Promise<Date>;
+    /** Retrieves an existing authorization code. */
+    get(code: string): Promise<AuthorizationCode<Client, User, Scope> | undefined>;
+    /**
+     * Saves an authorization code, preserving its `authenticationContext`
+     * snapshot on save and retrieval. Leave legacy context absent.
+     */
+    save(authorizationCode: AuthorizationCode<Client, User, Scope>): Promise<AuthorizationCode<Client, User, Scope>>;
+    /**
+     * Revokes an authorization code, accepting the record or its raw string.
+     *
+     * **Implementations must compare and delete atomically.** The authorization
+     * code grant claims a code by revoking it and issues a token only to the
+     * caller whose revoke resolved `true`, so this boolean is the single-use
+     * guarantee (RFC 6749 §4.1.2): resolve `true` only for the call that removed
+     * a live code, and `false` for every other call — a code already revoked,
+     * expired, or never stored. An implementation that reads then deletes in two
+     * steps, or that returns `true` unconditionally, lets two concurrent
+     * exchanges of one code both mint tokens. In SQL this is a
+     * `DELETE ... WHERE code = $1` whose affected-row count is the answer.
+     */
+    revoke(authorizationCode: AuthorizationCode<Client, User, Scope> | string): Promise<boolean>;
+}
+/** Options for configuring an abstract authorization code service. */
+export interface AbstractAuthorizationCodeServiceOptions<Client extends ClientInterface, User> {
+    /** Lifetime of authorization codes in seconds. Defaults to 600 (10 minutes). */
+    lifetime?: number;
+    /** Client service for hydrating authorization codes. */
+    clientService?: ClientServiceInterface<Client, User>;
+    /** User service for hydrating authorization codes. */
+    userService?: UserServiceInterface<User>;
+}
+/**
+ * Abstract authorization code service with sensible defaults.
+ *
+ * Provides default implementations for:
+ * - `generateCode` — crypto.randomUUID()
+ * - `expiresAt` — based on lifetime setting
+ *
+ * Subclasses must implement the storage methods: `get`, `save`, `revoke`
+ */
+export declare abstract class AbstractAuthorizationCodeService<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> implements AuthorizationCodeServiceInterface<Client, User, Scope> {
+    /** Lifetime of authorization codes in seconds. */
+    lifetime: number;
+    /** Client service used by subclasses to hydrate authorization codes. */
+    protected clientService?: ClientServiceInterface<Client, User>;
+    /** User service used by subclasses to hydrate authorization codes. */
+    protected userService?: UserServiceInterface<User>;
+    /** Lifetime defaults to 600 seconds (10 minutes) when not supplied. */
+    constructor(options?: AbstractAuthorizationCodeServiceOptions<Client, User>);
+    /** Generates an opaque authorization code string via `crypto.randomUUID()`. */
+    generateCode(_client: Client, _user: User, _scope?: Scope | null): Promise<string>;
+    /** Computes the code expiry as now plus {@linkcode lifetime}. */
+    expiresAt(_client: Client, _user: User, _scope?: Scope | null): Promise<Date>;
+    /** Retrieves a persisted authorization code by its string value. */
+    abstract get(code: string): Promise<AuthorizationCode<Client, User, Scope> | undefined>;
+    /** Persists an authorization code and returns the saved record. */
+    abstract save(authorizationCode: AuthorizationCode<Client, User, Scope>): Promise<AuthorizationCode<Client, User, Scope>>;
+    /**
+     * Revokes an authorization code given as a record or string. Resolves `true`
+     * only for the call that removed a live code, and `false` for every other
+     * call; the compare and delete must be atomic, since the authorization code
+     * grant relies on this boolean for single use.
+     */
+    abstract revoke(authorizationCode: AuthorizationCode<Client, User, Scope> | string): Promise<boolean>;
+}

package/esm/server/services/authorization-code.js

@@ -0,0 +1,35 @@
+/**
+ * Authorization code service interface and abstract implementation.
+ * @module
+ */
+/**
+ * Abstract authorization code service with sensible defaults.
+ *
+ * Provides default implementations for:
+ * - `generateCode` — crypto.randomUUID()
+ * - `expiresAt` — based on lifetime setting
+ *
+ * Subclasses must implement the storage methods: `get`, `save`, `revoke`
+ */
+export class AbstractAuthorizationCodeService {
+    /** Lifetime of authorization codes in seconds. */
+    lifetime;
+    /** Client service used by subclasses to hydrate authorization codes. */
+    clientService;
+    /** User service used by subclasses to hydrate authorization codes. */
+    userService;
+    /** Lifetime defaults to 600 seconds (10 minutes) when not supplied. */
+    constructor(options) {
+        this.lifetime = options?.lifetime ?? 600;
+        this.clientService = options?.clientService;
+        this.userService = options?.userService;
+    }
+    /** Generates an opaque authorization code string via `crypto.randomUUID()`. */
+    generateCode(_client, _user, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /** Computes the code expiry as now plus {@linkcode lifetime}. */
+    expiresAt(_client, _user, _scope) {
+        return Promise.resolve(new Date(Date.now() + this.lifetime * 1000));
+    }
+}

package/esm/server/services/client.d.ts

@@ -0,0 +1,35 @@
+import type { ClientInterface } from "../../models/client.js";
+/**
+ * Service interface for client management.
+ */
+export interface ClientServiceInterface<Client extends ClientInterface, User> {
+    /** Retrieves a client by ID. */
+    get(id: string): Promise<Client | undefined>;
+    /**
+     * Authenticates a client from the credentials a request presented, resolving
+     * the client on success and `undefined` on failure. The authorization server
+     * answers `undefined` with `invalid_client`.
+     *
+     * A client registered with a secret is confidential; one registered without
+     * a secret is public:
+     *
+     * - A **public** client must resolve when `secret` is omitted. The server
+     *   always advertises `none` in `token_endpoint_auth_methods_supported`, so
+     *   an implementation that demands a secret from every client makes that
+     *   advertisement false.
+     * - A **confidential** client resolves only with its correct `secret`. With
+     *   the secret missing or wrong, resolve `undefined`.
+     *
+     * `runClientServiceContractTests` from `@udibo/oauth2/testing/contract` pins
+     * both rules; run it against your implementation. It does not pin whether a
+     * public client that presents a `secret` resolves, so do not rely on either
+     * answer.
+     *
+     * @param id The presented `client_id` — unauthenticated input.
+     * @param secret The presented `client_secret`, omitted when the request
+     * carried none.
+     */
+    getAuthenticated(id: string, secret?: string): Promise<Client | undefined>;
+    /** Retrieves a user associated with a client (for client-credentials grant). */
+    getUser(client: Client | string): Promise<User | undefined>;
+}

package/esm/server/services/client.js

@@ -0,0 +1 @@
+export {};

package/esm/server/services/device-authorization.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Device authorization service interface for the Device Authorization Grant (RFC 8628).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { DeviceAuthorization } from "../../models/device-authorization.js";
+import type { AbstractScope } from "../../models/scope.js";
+/**
+ * Service interface for managing device authorizations.
+ *
+ * Implementations must handle:
+ * - Generating and storing device codes and user codes
+ * - Looking up device codes for polling
+ * - Looking up user codes for user authorization
+ * - Marking codes as authorized or denied
+ * - Cleaning up expired codes
+ *
+ * **Every method taking a `DeviceAuthorization` must accept the records this
+ * same service returns**, not only a record the caller assembled. A store that
+ * looks a record up by one code commonly returns it carrying only that code —
+ * {@linkcode DeviceAuthorizationServiceInterface.getByUserCode} has no device
+ * code to fill in — so resolve the stored authorization by whichever code the
+ * argument carries rather than by assuming both are populated. The grant hands
+ * {@linkcode DeviceAuthorizationServiceInterface.updateLastPolled} and
+ * {@linkcode DeviceAuthorizationServiceInterface.revoke} the record from
+ * `getByDeviceCode`, and a verification page hands
+ * {@linkcode DeviceAuthorizationServiceInterface.approve},
+ * {@linkcode DeviceAuthorizationServiceInterface.deny} and `revoke` the record
+ * from `getByUserCode`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+export interface DeviceAuthorizationServiceInterface<Client extends ClientInterface, User, Scope extends AbstractScope> {
+    /**
+     * Lifetime of device codes in seconds.
+     * RFC 8628 does not specify a default, but 15-30 minutes is common.
+     * @default 1800 (30 minutes)
+     */
+    lifetime: number;
+    /**
+     * Minimum polling interval in seconds.
+     * Clients should not poll more frequently than this.
+     * @default 5
+     */
+    interval: number;
+    /**
+     * Generates a unique device code.
+     *
+     * The device code is a long, high-entropy string used by the client
+     * to poll for authorization status.
+     */
+    generateDeviceCode(client: Client, scope?: Scope | null): Promise<string>;
+    /**
+     * Generates a user code.
+     *
+     * The user code should be short and easy for users to type.
+     * Common formats include: ABCD-1234, WDJB-MJHT, 12345678
+     */
+    generateUserCode(client: Client, scope?: Scope | null): Promise<string>;
+    /**
+     * Returns when the codes should expire.
+     */
+    expiresAt(client: Client, scope?: Scope | null): Promise<Date>;
+    /**
+     * Saves a device authorization request.
+     */
+    save(authorization: DeviceAuthorization<Client, User, Scope>): Promise<DeviceAuthorization<Client, User, Scope>>;
+    /**
+     * Gets a device authorization by device code.
+     *
+     * Used by the client when polling for authorization status.
+     */
+    getByDeviceCode(deviceCode: string): Promise<DeviceAuthorization<Client, User, Scope> | undefined>;
+    /**
+     * Gets a device authorization by user code.
+     *
+     * Used during user authorization to look up the pending request.
+     */
+    getByUserCode(userCode: string): Promise<DeviceAuthorization<Client, User, Scope> | undefined>;
+    /**
+     * Marks a device authorization as authorized by the user.
+     *
+     * @param authorization The authorization to approve
+     * @param user The user who approved the request
+     * @param scope Optional scope (may be narrower than originally requested)
+     */
+    approve(authorization: DeviceAuthorization<Client, User, Scope>, user: User, scope?: Scope | null): Promise<DeviceAuthorization<Client, User, Scope>>;
+    /**
+     * Marks a device authorization as denied by the user.
+     */
+    deny(authorization: DeviceAuthorization<Client, User, Scope>): Promise<DeviceAuthorization<Client, User, Scope>>;
+    /**
+     * Updates the last polled time for a device authorization.
+     *
+     * Used to track polling frequency and enforce slow_down errors.
+     *
+     * **A failure here is re-classified by re-reading the device code.** The
+     * grant calls this only on the non-terminal polling path, and when it
+     * rejects, the grant asks {@linkcode
+     * DeviceAuthorizationServiceInterface.getByDeviceCode} whether the record is
+     * still stored: gone means a concurrent poll claimed it, and the caller is
+     * refused `invalid_grant`; still there means the store itself failed, and
+     * the original error propagates. **That read must therefore be at least as
+     * fresh as the write that just failed** — serve it from the primary, never a
+     * replica that can lag behind it, or a transient write failure on a live
+     * authorization will tell a legitimate device its code was already used,
+     * which RFC 8628 §3.5 makes terminal.
+     */
+    updateLastPolled(authorization: DeviceAuthorization<Client, User, Scope>): Promise<DeviceAuthorization<Client, User, Scope>>;
+    /**
+     * Revokes a device authorization, accepting the record or its raw device code.
+     *
+     * **Implementations must compare and delete atomically.** The device
+     * authorization grant claims an approved authorization by revoking it and
+     * issues a token only to the caller whose revoke resolved `true`, so this
+     * boolean is the single-use guarantee (RFC 8628 §3.5): resolve `true` only
+     * for the call that removed a live authorization, and `false` for every other
+     * call — one already revoked, expired, or never stored. An implementation
+     * that reads then deletes in two steps, or that returns `true`
+     * unconditionally, lets two concurrent polls of one device code both mint
+     * tokens. In SQL this is a `DELETE ... WHERE device_code = $1` whose
+     * affected-row count is the answer.
+     *
+     * **The authorization must become unreachable by both of its codes.** A
+     * verification page revokes the record it read from
+     * {@linkcode DeviceAuthorizationServiceInterface.getByUserCode} to cancel a
+     * request; if that leaves the device-code entry behind, the device's next
+     * poll still redeems the cancelled — possibly already approved —
+     * authorization for a token.
+     */
+    revoke(authorization: DeviceAuthorization<Client, User, Scope> | string): Promise<boolean>;
+}

package/esm/server/services/device-authorization.js

@@ -0,0 +1,7 @@
+/**
+ * Device authorization service interface for the Device Authorization Grant (RFC 8628).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ * @module
+ */
+export {};