@julr/sesame 0.6.0 → 0.7.0

package/build/src/storage/types.d.ts

@@ -0,0 +1,197 @@
+import type { DateTime } from 'luxon';
+/**
+ * Stored OAuth client. `clientSecret` is a hash and must never be exposed
+ * in public responses.
+ */
+export interface OAuthClientRecord {
+    id: string;
+    clientId: string;
+    clientSecret: string | null;
+    name: string;
+    redirectUris: string[];
+    scopes: string[];
+    grantTypes: string[];
+    isPublic: boolean;
+    isDisabled: boolean;
+    requirePkce: boolean;
+    type: string | null;
+    metadata: Record<string, any> | null;
+    userId: string | null;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export interface OAuthAccessTokenRecord {
+    id: string;
+    tokenHash: string;
+    clientId: string;
+    userId: string | null;
+    scopes: string[];
+    expiresAt: DateTime;
+    revokedAt: DateTime | null;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export interface OAuthRefreshTokenRecord {
+    id: string;
+    token: string;
+    accessTokenId: string;
+    clientId: string;
+    userId: string;
+    scopes: string[];
+    expiresAt: DateTime;
+    revokedAt: DateTime | null;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export interface OAuthAuthorizationCodeRecord {
+    id: string;
+    code: string;
+    clientId: string;
+    userId: string;
+    scopes: string[];
+    redirectUri: string;
+    codeChallenge: string | null;
+    codeChallengeMethod: string | null;
+    nonce: string | null;
+    expiresAt: DateTime;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export interface OAuthConsentRecord {
+    id: string;
+    clientId: string;
+    userId: string;
+    scopes: string[];
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export interface OAuthPendingAuthorizationRequestRecord {
+    id: string;
+    token: string;
+    userId: string;
+    clientId: string;
+    redirectUri: string;
+    scopes: string[];
+    state: string | null;
+    codeChallenge: string | null;
+    codeChallengeMethod: string | null;
+    nonce: string | null;
+    expiresAt: DateTime;
+    createdAt: DateTime;
+}
+type SesameOptionalCreateKeys<T> = Extract<keyof T, 'createdAt' | 'updatedAt'> | {
+    [K in keyof T]-?: null extends T[K] ? K : never;
+}[keyof T];
+/**
+ * Nullable fields default to null; timestamps default to the current time.
+ */
+export type SesameCreateRecord<T> = Omit<T, SesameOptionalCreateKeys<T>> & Partial<Pick<T, SesameOptionalCreateKeys<T>>>;
+/**
+ * Creation input for each persisted OAuth record.
+ */
+export type CreateClientRecord = SesameCreateRecord<OAuthClientRecord>;
+export type CreateAccessTokenRecord = SesameCreateRecord<OAuthAccessTokenRecord>;
+export type CreateRefreshTokenRecord = SesameCreateRecord<OAuthRefreshTokenRecord>;
+export type CreateAuthorizationCodeRecord = SesameCreateRecord<OAuthAuthorizationCodeRecord>;
+export type CreatePendingAuthorizationRequestRecord = SesameCreateRecord<OAuthPendingAuthorizationRequestRecord>;
+export type UpdateClientRecord = Partial<Pick<OAuthClientRecord, 'name' | 'redirectUris' | 'scopes' | 'grantTypes' | 'isDisabled' | 'requirePkce' | 'metadata'>>;
+export interface SesamePurgeResult {
+    accessTokens: number;
+    refreshTokens: number;
+    authorizationCodes: number;
+    pendingRequests: number;
+}
+export interface IssueTokenPairOptions {
+    accessToken: CreateAccessTokenRecord;
+    refreshToken: CreateRefreshTokenRecord;
+}
+export interface ExchangeAuthorizationCodeOptions {
+    codeId: string;
+    accessToken: CreateAccessTokenRecord;
+    refreshToken: CreateRefreshTokenRecord | null;
+}
+export interface RotateRefreshTokenOptions extends IssueTokenPairOptions {
+    oldRefreshTokenId: string;
+    oldAccessTokenId: string;
+    revokedAt: DateTime;
+}
+export interface PurgeTokensOptions {
+    purgeRevoked: boolean;
+    purgeExpired: boolean;
+    cutoff: DateTime;
+    now: DateTime;
+}
+/**
+ * OAuth-specific persistence operations. Callers never build database predicates.
+ * Conditional exchanges and rotations return false when another request won.
+ */
+export interface SesameStore {
+    findClient(clientId: string): Promise<OAuthClientRecord | null>;
+    listClients(options?: {
+        userId?: string;
+    }): Promise<OAuthClientRecord[]>;
+    createClient(data: CreateClientRecord): Promise<OAuthClientRecord>;
+    updateClient(options: {
+        id: string;
+        data: UpdateClientRecord;
+    }): Promise<void>;
+    updateClientSecret(options: {
+        id: string;
+        secret: string;
+    }): Promise<void>;
+    deleteClient(clientId: string): Promise<boolean>;
+    findAccessToken(options: {
+        hash: string;
+        clientId?: string;
+    }): Promise<OAuthAccessTokenRecord | null>;
+    createAccessToken(data: CreateAccessTokenRecord): Promise<void>;
+    revokeAccessToken(options: {
+        hash: string;
+        clientId: string;
+        now: DateTime;
+    }): Promise<boolean>;
+    findRefreshToken(options: {
+        hash: string;
+        clientId: string;
+    }): Promise<OAuthRefreshTokenRecord | null>;
+    revokeRefreshToken(options: {
+        hash: string;
+        clientId: string;
+        now: DateTime;
+    }): Promise<void>;
+    revokeTokenFamily(options: {
+        clientId: string;
+        userId: string;
+        now: DateTime;
+    }): Promise<void>;
+    findAuthorizationCode(options: {
+        code: string;
+        clientId: string;
+    }): Promise<OAuthAuthorizationCodeRecord | null>;
+    createAuthorizationCode(data: CreateAuthorizationCodeRecord): Promise<void>;
+    deleteAuthorizationCode(id: string): Promise<void>;
+    exchangeAuthorizationCode(options: ExchangeAuthorizationCodeOptions): Promise<boolean>;
+    findConsent(options: {
+        clientId: string;
+        userId: string;
+    }): Promise<OAuthConsentRecord | null>;
+    grantConsent(options: {
+        clientId: string;
+        userId: string;
+        scopes: string[];
+    }): Promise<void>;
+    createPendingAuthorizationRequest(data: CreatePendingAuthorizationRequestRecord): Promise<void>;
+    consumePendingAuthorizationRequest(options: {
+        token: string;
+        userId: string;
+        now: DateTime;
+    }): Promise<OAuthPendingAuthorizationRequestRecord | null>;
+    issueTokenPair(options: IssueTokenPairOptions): Promise<void>;
+    rotateRefreshToken(options: RotateRefreshTokenOptions): Promise<boolean>;
+    revokeAllForUser(options: {
+        userId: string;
+        now: DateTime;
+    }): Promise<void>;
+    purgeTokens(options: PurgeTokensOptions): Promise<SesamePurgeResult>;
+}
+export {};

package/build/src/storage/types.js

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

package/build/src/stores.d.ts

@@ -0,0 +1,21 @@
+import type { ApplicationService, ConfigProvider } from '@adonisjs/core/types';
+import type { Kysely } from 'kysely';
+import type { SesameStore } from './storage/types.ts';
+import type { KyselyDialect } from './storage/drivers/kysely.ts';
+export interface KyselyStoreConfig<DB> {
+    connection: Kysely<DB> | ((app: ApplicationService) => Kysely<DB> | Promise<Kysely<DB>>);
+    dialect?: KyselyDialect;
+}
+/**
+ * Store driver factories resolved by the AdonisJS service provider.
+ */
+export declare const stores: {
+    /**
+     * Use the application's Lucid connection for OAuth persistence.
+     */
+    lucid(): ConfigProvider<SesameStore>;
+    /**
+     * Use an existing Kysely connection for OAuth persistence.
+     */
+    kysely<DB>(options: KyselyStoreConfig<DB>): ConfigProvider<SesameStore>;
+};

package/build/src/types.d.ts

@@ -1,6 +1,9 @@
 import type { HttpContext } from '@adonisjs/core/http';
+import type { ConfigProvider } from '@adonisjs/core/types';
 import type { JWK } from 'jose';
 import type { OAuthUserProviderContract } from './guard/types.ts';
+import type { OAuthClientRecord, SesameStore } from './storage/types.ts';
+export type * from './storage/types.ts';
 /**
  * Augment this interface via module augmentation to enable
  * type-safe scope names across the application.
@@ -131,7 +134,7 @@ export interface UpdateClientOptions {
  * Includes the raw secret (only available at creation time).
  */
 export interface CreateClientResult {
-    client: import('./models/oauth_client.ts').OAuthClient;
+    client: OAuthClientRecord;
     clientSecret: string | null;
 }
 /**
@@ -142,6 +145,10 @@ export interface CreateClientResult {
  * page redirects for the authorization flow.
  */
 export interface SesameConfig {
+    /**
+     * Store driver resolved by the service provider.
+     */
+    store: ConfigProvider<SesameStore>;
     /**
      * The issuer URL (must be HTTPS in production).
      * Used in JWT `iss` claim and discovery metadata.
@@ -256,6 +263,7 @@ export interface SesameConfig {
  * Created by `defineConfig()` from user-supplied `SesameConfig`.
  */
 export interface ResolvedSesameConfig {
+    store: ConfigProvider<SesameStore>;
     issuer: string;
     scopes: Record<string, string>;
     defaultScopes: string[];

package/build/src/types.js

@@ -0,0 +1,2 @@
+import { i as collectOidcClaims, n as OIDC_SCOPES, r as RESERVED_OIDC_CLAIMS, t as BUILTIN_SCOPES } from "../types-DEtn2Zdb.js";
+export { BUILTIN_SCOPES, OIDC_SCOPES, RESERVED_OIDC_CLAIMS, collectOidcClaims };

package/build/stubs/config/sesame.stub

@@ -1,12 +1,15 @@
 {{{
-  exports: { defineConfig: 'import { defineConfig } from \'@julr/sesame\'' }
+  exports({ to: app.configPath('sesame.ts') })
 }}}
 import env from '#start/env'
+import { defineConfig, stores } from '@julr/sesame'
 import type { InferScopes } from '@julr/sesame/types'
 
 const sesameConfig = defineConfig({
   issuer: env.get('APP_URL'),
 
+  store: stores.lucid(),
+
   scopes: {
     // Define your available scopes here
     // 'read': 'Read access',

package/build/stubs/config/sesame_kysely.stub

@@ -0,0 +1,35 @@
+{{{
+  exports({ to: app.configPath('sesame.ts') })
+}}}
+import env from '#start/env'
+import { defineConfig, stores } from '@julr/sesame'
+import type { InferScopes } from '@julr/sesame/types'
+
+const sesameConfig = defineConfig({
+  issuer: env.get('APP_URL'),
+
+  // Replace this import with your application's Kysely instance.
+  store: stores.kysely({
+    connection: async () => {
+      const { db } = await import('#services/kysely')
+      return db
+    },
+  }),
+
+  scopes: {},
+  defaultScopes: [],
+  grantTypes: ['authorization_code', 'refresh_token'],
+  accessTokenTtl: '1h',
+  refreshTokenTtl: '30d',
+  authorizationCodeTtl: '10m',
+  loginPage: '/login',
+  consentPage: '/oauth/consent',
+  allowDynamicRegistration: false,
+  allowPublicRegistration: false,
+})
+
+export default sesameConfig
+
+declare module '@julr/sesame/types' {
+  interface SesameScopes extends InferScopes<typeof sesameConfig> {}
+}

package/build/stubs/migrations/kysely/create_oauth_tables.stub

@@ -0,0 +1,151 @@
+{{{
+  exports({
+    to: app.makePath('database/kysely_migrations/create_oauth_tables.ts')
+  })
+}}}
+
+import type { Kysely } from 'kysely'
+
+/**
+ * Kysely migration for Sesame's OAuth tables.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  // Clients own OAuth grants and define the allowed redirects, scopes, and grant types.
+  await db.schema
+    .createTable('oauth_clients')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('client_id', 'varchar(255)', (column) => column.notNull().unique())
+    .addColumn('client_secret', 'text')
+    .addColumn('name', 'varchar(255)', (column) => column.notNull())
+    .addColumn('redirect_uris', 'json', (column) => column.notNull())
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('grant_types', 'json', (column) => column.notNull())
+    .addColumn('is_public', 'boolean', (column) => column.notNull().defaultTo(false))
+    .addColumn('is_disabled', 'boolean', (column) => column.notNull().defaultTo(false))
+    .addColumn('require_pkce', 'boolean', (column) => column.notNull().defaultTo(true))
+    .addColumn('type', 'varchar(255)')
+    .addColumn('metadata', 'json')
+    .addColumn('user_id', 'varchar(255)')
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .addColumn('updated_at', 'timestamp', (column) => column.notNull())
+    .execute()
+
+  // Access tokens are stored by hash so a leaked database never exposes bearer tokens.
+  await db.schema
+    .createTable('oauth_access_tokens')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('token_hash', 'varchar(255)', (column) => column.notNull().unique())
+    .addColumn('client_id', 'varchar(255)', (column) =>
+      column.notNull().references('oauth_clients.client_id').onDelete('cascade')
+    )
+    .addColumn('user_id', 'varchar(255)')
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('expires_at', 'timestamp', (column) => column.notNull())
+    .addColumn('revoked_at', 'timestamp')
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .addColumn('updated_at', 'timestamp', (column) => column.notNull())
+    .execute()
+
+  // Refresh tokens point to their access token so rotation can revoke the old pair.
+  await db.schema
+    .createTable('oauth_refresh_tokens')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('token', 'varchar(255)', (column) => column.notNull())
+    .addColumn('access_token_id', 'varchar(36)', (column) => column.notNull())
+    .addColumn('client_id', 'varchar(255)', (column) =>
+      column.notNull().references('oauth_clients.client_id').onDelete('cascade')
+    )
+    .addColumn('user_id', 'varchar(255)', (column) => column.notNull())
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('expires_at', 'timestamp', (column) => column.notNull())
+    .addColumn('revoked_at', 'timestamp')
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .addColumn('updated_at', 'timestamp', (column) => column.notNull())
+    .execute()
+  // Token lookup is part of the refresh grant's hot path.
+  await db.schema
+    .createIndex('oauth_refresh_tokens_token_idx')
+    .on('oauth_refresh_tokens')
+    .column('token')
+    .execute()
+
+  // Authorization codes are short-lived, single-use credentials for the code grant.
+  await db.schema
+    .createTable('oauth_authorization_codes')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('code', 'varchar(255)', (column) => column.notNull())
+    .addColumn('client_id', 'varchar(255)', (column) =>
+      column.notNull().references('oauth_clients.client_id').onDelete('cascade')
+    )
+    .addColumn('user_id', 'varchar(255)', (column) => column.notNull())
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('redirect_uri', 'text', (column) => column.notNull())
+    .addColumn('code_challenge', 'varchar(255)')
+    .addColumn('code_challenge_method', 'varchar(255)')
+    .addColumn('nonce', 'varchar(255)')
+    .addColumn('expires_at', 'timestamp', (column) => column.notNull())
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .addColumn('updated_at', 'timestamp', (column) => column.notNull())
+    .execute()
+  // Locate the authorization code submitted to the token endpoint.
+  await db.schema
+    .createIndex('oauth_authorization_codes_code_idx')
+    .on('oauth_authorization_codes')
+    .column('code')
+    .execute()
+
+  // A consent records the scopes approved by one user for one client.
+  await db.schema
+    .createTable('oauth_consents')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('client_id', 'varchar(255)', (column) =>
+      column.notNull().references('oauth_clients.client_id').onDelete('cascade')
+    )
+    .addColumn('user_id', 'varchar(255)', (column) => column.notNull())
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .addColumn('updated_at', 'timestamp', (column) => column.notNull())
+    .execute()
+  // Only one consent record may exist for a client and user pair.
+  await db.schema
+    .createIndex('oauth_consents_client_id_user_id_unique')
+    .on('oauth_consents')
+    .columns(['client_id', 'user_id'])
+    .unique()
+    .execute()
+
+  // Pending requests carry the authorization context across the consent redirect.
+  await db.schema
+    .createTable('oauth_pending_authorization_requests')
+    .addColumn('id', 'varchar(36)', (column) => column.primaryKey())
+    .addColumn('token', 'varchar(255)', (column) => column.notNull())
+    .addColumn('client_id', 'varchar(255)', (column) =>
+      column.notNull().references('oauth_clients.client_id').onDelete('cascade')
+    )
+    .addColumn('user_id', 'varchar(255)', (column) => column.notNull())
+    .addColumn('scopes', 'json', (column) => column.notNull())
+    .addColumn('redirect_uri', 'text', (column) => column.notNull())
+    .addColumn('state', 'varchar(255)')
+    .addColumn('code_challenge', 'varchar(255)')
+    .addColumn('code_challenge_method', 'varchar(255)')
+    .addColumn('nonce', 'varchar(255)')
+    .addColumn('expires_at', 'timestamp', (column) => column.notNull())
+    .addColumn('created_at', 'timestamp', (column) => column.notNull())
+    .execute()
+  // Resolve the opaque pending-request token when the consent form returns.
+  await db.schema
+    .createIndex('oauth_pending_authorization_requests_token_idx')
+    .on('oauth_pending_authorization_requests')
+    .column('token')
+    .execute()
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  // Drop children before clients to respect the client foreign keys.
+  await db.schema.dropTable('oauth_pending_authorization_requests').execute()
+  await db.schema.dropTable('oauth_consents').execute()
+  await db.schema.dropTable('oauth_authorization_codes').execute()
+  await db.schema.dropTable('oauth_refresh_tokens').execute()
+  await db.schema.dropTable('oauth_access_tokens').execute()
+  await db.schema.dropTable('oauth_clients').execute()
+}

package/build/taze.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Partial<import("taze").CheckOptions>;
+export default _default;