@ttoss/auth-postgresdb 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,244 @@
+
+import { AuthCodeStore, ClientStore, ConsentGrant, ConsentGrantStore, RefreshTokenStore } from "@ttoss/auth-core";
+import { Model } from "@ttoss/postgresdb";
+
+//#region src/models/OAuthAuthCode.d.ts
+/**
+ * A short-lived authorization code with its bound PKCE challenge.
+ *
+ * The primary key is the code's SHA-256 hash, never the code itself: a code
+ * travels through a browser redirect and a client's URL bar, so storing it in
+ * plaintext would make a database dump yield replayable codes.
+ */
+declare class OAuthAuthCode extends Model {
+  /** SHA-256 hash (hex) of the authorization code. */
+  codeHash: string;
+  /** The `client_id` the code was issued to. */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match on exchange). */
+  redirectUri: string;
+  /** The PKCE `code_challenge` (S256) bound to this code. */
+  codeChallenge: string;
+  /** The scopes granted to this code. */
+  scopes: string[];
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** Instant after which the code is invalid. */
+  expiresAt: Date;
+}
+//#endregion
+//#region src/models/OAuthClient.d.ts
+/**
+ * A registered OAuth client (RFC 7591 dynamic client registration).
+ *
+ * The RFC's registered fields get their own columns so they can be queried and
+ * indexed; any additional metadata a client submits is kept verbatim in
+ * `metadata`, because `OAuthClientMetadata` is an open shape.
+ */
+declare class OAuthClient extends Model {
+  /** The `client_id` issued by the authorization server. */
+  clientId: string;
+  /**
+   * Client secret for confidential clients, `null` for public clients
+   * (`token_endpoint_auth_method: 'none'`).
+   */
+  clientSecret: string | null;
+  /** Human-readable client name shown on consent screens. */
+  clientName: string | null;
+  /** Exact redirect URIs registered for this client. */
+  redirectUris: string[];
+  /** OAuth grant types the client may use. */
+  grantTypes: string[] | null;
+  /** OAuth response types the client may use. */
+  responseTypes: string[] | null;
+  /** Client authentication method at the token endpoint. */
+  tokenEndpointAuthMethod: string | null;
+  /** Space-separated scopes the client may request. */
+  scope: string | null;
+  /** Unix timestamp (seconds) when the client was registered. */
+  clientIdIssuedAt: number | null;
+  /**
+   * Registration metadata outside the columns above, preserved so a client's
+   * submitted document round-trips unchanged (e.g. `logo_uri`, `client_uri`).
+   */
+  metadata: Record<string, unknown>;
+}
+//#endregion
+//#region src/models/OAuthConsent.d.ts
+/**
+ * A single-use consent handoff, correlated by the PKCE `code_challenge`.
+ *
+ * This is the record an external consent screen writes on approval so the
+ * restarted `/authorize` request can be approved without asking again — it is
+ * not a durable "user X trusts client Y" grant, which is an app-level
+ * authorization decision and belongs in the app's own schema.
+ */
+declare class OAuthConsent extends Model {
+  /** The PKCE `code_challenge` the consent was recorded against. */
+  codeChallenge: string;
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes the user approved. */
+  scopes: string[];
+  /** Instant after which the consent is no longer usable. */
+  expiresAt: Date;
+}
+//#endregion
+//#region src/models/OAuthRefreshToken.d.ts
+/**
+ * A refresh token tracked for OAuth 2.1 rotation, stored by hash so a database
+ * dump yields no usable credentials.
+ *
+ * `consumedAt` marks a rotated token. Presenting one again is reuse, and
+ * `createRefreshRotation` revokes the whole `(clientId, subject)` token set —
+ * which is why the store adapter must report a live token's `consumedAt` as
+ * absent rather than as `null`.
+ */
+declare class OAuthRefreshToken extends Model {
+  /** SHA-256 hash (hex) of the opaque refresh token. */
+  tokenHash: string;
+  /** The `client_id` the token was issued to. */
+  clientId: string;
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes granted to this token. */
+  scopes: string[];
+  /** Instant after which the token is invalid. */
+  expiresAt: Date;
+  /** Instant the token was rotated (consumed), or `null` while it is live. */
+  consumedAt: Date | null;
+}
+//#endregion
+//#region src/models/index.d.ts
+/**
+ * The OAuth data model, ready to register alongside the application's own
+ * models so `ttoss-postgresdb sync` and `erd` cover these tables like any
+ * other instead of them being a side-channel schema the CLI cannot see.
+ *
+ * @example
+ * ```typescript
+ * import { oauthModels } from '@ttoss/auth-postgresdb';
+ * import { initialize } from '@ttoss/postgresdb';
+ *
+ * export const db = await initialize({ models: { ...oauthModels, User } });
+ * ```
+ */
+declare const oauthModels: {
+  OAuthAuthCode: typeof OAuthAuthCode;
+  OAuthClient: typeof OAuthClient;
+  OAuthConsent: typeof OAuthConsent;
+  OAuthRefreshToken: typeof OAuthRefreshToken;
+};
+/** The shape a `db` handle must have to back the OAuth stores. */
+type OAuthModels = typeof oauthModels;
+//#endregion
+//#region src/stores/createConsentStore.d.ts
+/** A {@link ConsentGrantStore} plus the write side an app's consent page needs. */
+interface PostgresdbConsentStore extends ConsentGrantStore {
+  /**
+   * Record an approval so the restarted `/authorize` request can consume it.
+   * Call this from the consent page's approve handler, before navigating back
+   * to the authorization server's `/authorize`.
+   */
+  saveConsentGrant: (grant: ConsentGrant & {
+    codeChallenge: string;
+  }) => Promise<void>;
+}
+/**
+ * Creates a consent store backed by the `oauth_consents` table, for use with
+ * `createRedirectConsentOnAuthorize`.
+ *
+ * Reads and deletes satisfy `ConsentGrantStore`; `saveConsentGrant` covers the
+ * write the consent page performs. Grants are single-use — the `onAuthorize`
+ * hook deletes each one as it consumes it.
+ */
+declare const createConsentStore: ({
+  model
+}: {
+  /** The `OAuthConsent` model class, taken from the app's `db` handle. */model: typeof OAuthConsent;
+}) => PostgresdbConsentStore;
+//#endregion
+//#region src/createPostgresdbOAuthStores.d.ts
+/** The durable OAuth stores returned by {@link createPostgresdbOAuthStores}. */
+interface PostgresdbOAuthStores {
+  /** Dynamic client registrations, for `createOAuthHandlers`. */
+  clientStore: ClientStore;
+  /** Single-use authorization codes, stored by hash. */
+  authCodeStore: AuthCodeStore;
+  /** Consent handoff records for `createRedirectConsentOnAuthorize`. */
+  consentStore: PostgresdbConsentStore;
+  /** Tracked refresh tokens, for `createRefreshRotation`. */
+  refreshTokenStore: RefreshTokenStore;
+}
+/**
+ * Creates every durable OAuth store from a `@ttoss/postgresdb` `db` handle.
+ *
+ * The stores are mechanical adapters between the `@ttoss/auth-core` store
+ * contracts and Sequelize, so an app that already uses `@ttoss/postgresdb` does
+ * not have to write them — nor reach around its own ORM to inject a raw `pg`
+ * query runner.
+ *
+ * @example
+ * ```typescript
+ * import { createPostgresdbOAuthStores, oauthModels } from '@ttoss/auth-postgresdb';
+ * import { initialize } from '@ttoss/postgresdb';
+ *
+ * const db = await initialize({ models: { ...oauthModels, User } });
+ *
+ * const { clientStore, authCodeStore, consentStore, refreshTokenStore } =
+ *   createPostgresdbOAuthStores({ db });
+ * ```
+ */
+declare const createPostgresdbOAuthStores: ({
+  db
+}: {
+  /**
+   * The handle returned by `@ttoss/postgresdb`'s `initialize`, with
+   * `oauthModels` among its registered models.
+   */
+  db: OAuthModels;
+}) => PostgresdbOAuthStores;
+//#endregion
+//#region src/stores/createAuthCodeStore.d.ts
+/**
+ * Creates an {@link AuthCodeStore} backed by the `oauth_auth_codes` table,
+ * storing codes by SHA-256 hash.
+ *
+ * The engine hands the store the plaintext code on every call and never compares
+ * the returned `code` against anything — it reads only `clientId`,
+ * `redirectUri`, `codeChallenge`, `scopes`, `subject`, and `expiresAt`. So the
+ * adapter hashes to find the row and echoes the presented value back, and a
+ * database dump yields no replayable codes.
+ */
+declare const createAuthCodeStore: ({
+  model
+}: {
+  /** The `OAuthAuthCode` model class, taken from the app's `db` handle. */model: typeof OAuthAuthCode;
+}) => AuthCodeStore;
+//#endregion
+//#region src/stores/createClientStore.d.ts
+/**
+ * Creates a {@link ClientStore} backed by the `oauth_clients` table.
+ *
+ * `register` upserts, so re-registering an existing `client_id` replaces the
+ * stored document rather than failing on the primary key.
+ */
+declare const createClientStore: ({
+  model
+}: {
+  /** The `OAuthClient` model class, taken from the app's `db` handle. */model: typeof OAuthClient;
+}) => ClientStore;
+//#endregion
+//#region src/stores/createRefreshTokenStore.d.ts
+/**
+ * Creates a {@link RefreshTokenStore} backed by the `oauth_refresh_tokens`
+ * table, keyed by token hash and by the `(clientId, subject)` owner that
+ * `deleteByOwner` revokes on reuse detection.
+ */
+declare const createRefreshTokenStore: ({
+  model
+}: {
+  /** The `OAuthRefreshToken` model class, taken from the app's `db` handle. */model: typeof OAuthRefreshToken;
+}) => RefreshTokenStore;
+//#endregion
+export { OAuthAuthCode, OAuthClient, OAuthConsent, type OAuthModels, OAuthRefreshToken, type PostgresdbConsentStore, type PostgresdbOAuthStores, createAuthCodeStore, createClientStore, createConsentStore, createPostgresdbOAuthStores, createRefreshTokenStore, oauthModels };

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+
+import { AuthCodeStore, ClientStore, ConsentGrant, ConsentGrantStore, RefreshTokenStore } from "@ttoss/auth-core";
+import { Model } from "@ttoss/postgresdb";
+
+//#region src/models/OAuthAuthCode.d.ts
+/**
+ * A short-lived authorization code with its bound PKCE challenge.
+ *
+ * The primary key is the code's SHA-256 hash, never the code itself: a code
+ * travels through a browser redirect and a client's URL bar, so storing it in
+ * plaintext would make a database dump yield replayable codes.
+ */
+declare class OAuthAuthCode extends Model {
+  /** SHA-256 hash (hex) of the authorization code. */
+  codeHash: string;
+  /** The `client_id` the code was issued to. */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match on exchange). */
+  redirectUri: string;
+  /** The PKCE `code_challenge` (S256) bound to this code. */
+  codeChallenge: string;
+  /** The scopes granted to this code. */
+  scopes: string[];
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** Instant after which the code is invalid. */
+  expiresAt: Date;
+}
+//#endregion
+//#region src/models/OAuthClient.d.ts
+/**
+ * A registered OAuth client (RFC 7591 dynamic client registration).
+ *
+ * The RFC's registered fields get their own columns so they can be queried and
+ * indexed; any additional metadata a client submits is kept verbatim in
+ * `metadata`, because `OAuthClientMetadata` is an open shape.
+ */
+declare class OAuthClient extends Model {
+  /** The `client_id` issued by the authorization server. */
+  clientId: string;
+  /**
+   * Client secret for confidential clients, `null` for public clients
+   * (`token_endpoint_auth_method: 'none'`).
+   */
+  clientSecret: string | null;
+  /** Human-readable client name shown on consent screens. */
+  clientName: string | null;
+  /** Exact redirect URIs registered for this client. */
+  redirectUris: string[];
+  /** OAuth grant types the client may use. */
+  grantTypes: string[] | null;
+  /** OAuth response types the client may use. */
+  responseTypes: string[] | null;
+  /** Client authentication method at the token endpoint. */
+  tokenEndpointAuthMethod: string | null;
+  /** Space-separated scopes the client may request. */
+  scope: string | null;
+  /** Unix timestamp (seconds) when the client was registered. */
+  clientIdIssuedAt: number | null;
+  /**
+   * Registration metadata outside the columns above, preserved so a client's
+   * submitted document round-trips unchanged (e.g. `logo_uri`, `client_uri`).
+   */
+  metadata: Record<string, unknown>;
+}
+//#endregion
+//#region src/models/OAuthConsent.d.ts
+/**
+ * A single-use consent handoff, correlated by the PKCE `code_challenge`.
+ *
+ * This is the record an external consent screen writes on approval so the
+ * restarted `/authorize` request can be approved without asking again — it is
+ * not a durable "user X trusts client Y" grant, which is an app-level
+ * authorization decision and belongs in the app's own schema.
+ */
+declare class OAuthConsent extends Model {
+  /** The PKCE `code_challenge` the consent was recorded against. */
+  codeChallenge: string;
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes the user approved. */
+  scopes: string[];
+  /** Instant after which the consent is no longer usable. */
+  expiresAt: Date;
+}
+//#endregion
+//#region src/models/OAuthRefreshToken.d.ts
+/**
+ * A refresh token tracked for OAuth 2.1 rotation, stored by hash so a database
+ * dump yields no usable credentials.
+ *
+ * `consumedAt` marks a rotated token. Presenting one again is reuse, and
+ * `createRefreshRotation` revokes the whole `(clientId, subject)` token set —
+ * which is why the store adapter must report a live token's `consumedAt` as
+ * absent rather than as `null`.
+ */
+declare class OAuthRefreshToken extends Model {
+  /** SHA-256 hash (hex) of the opaque refresh token. */
+  tokenHash: string;
+  /** The `client_id` the token was issued to. */
+  clientId: string;
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes granted to this token. */
+  scopes: string[];
+  /** Instant after which the token is invalid. */
+  expiresAt: Date;
+  /** Instant the token was rotated (consumed), or `null` while it is live. */
+  consumedAt: Date | null;
+}
+//#endregion
+//#region src/models/index.d.ts
+/**
+ * The OAuth data model, ready to register alongside the application's own
+ * models so `ttoss-postgresdb sync` and `erd` cover these tables like any
+ * other instead of them being a side-channel schema the CLI cannot see.
+ *
+ * @example
+ * ```typescript
+ * import { oauthModels } from '@ttoss/auth-postgresdb';
+ * import { initialize } from '@ttoss/postgresdb';
+ *
+ * export const db = await initialize({ models: { ...oauthModels, User } });
+ * ```
+ */
+declare const oauthModels: {
+  OAuthAuthCode: typeof OAuthAuthCode;
+  OAuthClient: typeof OAuthClient;
+  OAuthConsent: typeof OAuthConsent;
+  OAuthRefreshToken: typeof OAuthRefreshToken;
+};
+/** The shape a `db` handle must have to back the OAuth stores. */
+type OAuthModels = typeof oauthModels;
+//#endregion
+//#region src/stores/createConsentStore.d.ts
+/** A {@link ConsentGrantStore} plus the write side an app's consent page needs. */
+interface PostgresdbConsentStore extends ConsentGrantStore {
+  /**
+   * Record an approval so the restarted `/authorize` request can consume it.
+   * Call this from the consent page's approve handler, before navigating back
+   * to the authorization server's `/authorize`.
+   */
+  saveConsentGrant: (grant: ConsentGrant & {
+    codeChallenge: string;
+  }) => Promise<void>;
+}
+/**
+ * Creates a consent store backed by the `oauth_consents` table, for use with
+ * `createRedirectConsentOnAuthorize`.
+ *
+ * Reads and deletes satisfy `ConsentGrantStore`; `saveConsentGrant` covers the
+ * write the consent page performs. Grants are single-use — the `onAuthorize`
+ * hook deletes each one as it consumes it.
+ */
+declare const createConsentStore: ({
+  model
+}: {
+  /** The `OAuthConsent` model class, taken from the app's `db` handle. */model: typeof OAuthConsent;
+}) => PostgresdbConsentStore;
+//#endregion
+//#region src/createPostgresdbOAuthStores.d.ts
+/** The durable OAuth stores returned by {@link createPostgresdbOAuthStores}. */
+interface PostgresdbOAuthStores {
+  /** Dynamic client registrations, for `createOAuthHandlers`. */
+  clientStore: ClientStore;
+  /** Single-use authorization codes, stored by hash. */
+  authCodeStore: AuthCodeStore;
+  /** Consent handoff records for `createRedirectConsentOnAuthorize`. */
+  consentStore: PostgresdbConsentStore;
+  /** Tracked refresh tokens, for `createRefreshRotation`. */
+  refreshTokenStore: RefreshTokenStore;
+}
+/**
+ * Creates every durable OAuth store from a `@ttoss/postgresdb` `db` handle.
+ *
+ * The stores are mechanical adapters between the `@ttoss/auth-core` store
+ * contracts and Sequelize, so an app that already uses `@ttoss/postgresdb` does
+ * not have to write them — nor reach around its own ORM to inject a raw `pg`
+ * query runner.
+ *
+ * @example
+ * ```typescript
+ * import { createPostgresdbOAuthStores, oauthModels } from '@ttoss/auth-postgresdb';
+ * import { initialize } from '@ttoss/postgresdb';
+ *
+ * const db = await initialize({ models: { ...oauthModels, User } });
+ *
+ * const { clientStore, authCodeStore, consentStore, refreshTokenStore } =
+ *   createPostgresdbOAuthStores({ db });
+ * ```
+ */
+declare const createPostgresdbOAuthStores: ({
+  db
+}: {
+  /**
+   * The handle returned by `@ttoss/postgresdb`'s `initialize`, with
+   * `oauthModels` among its registered models.
+   */
+  db: OAuthModels;
+}) => PostgresdbOAuthStores;
+//#endregion
+//#region src/stores/createAuthCodeStore.d.ts
+/**
+ * Creates an {@link AuthCodeStore} backed by the `oauth_auth_codes` table,
+ * storing codes by SHA-256 hash.
+ *
+ * The engine hands the store the plaintext code on every call and never compares
+ * the returned `code` against anything — it reads only `clientId`,
+ * `redirectUri`, `codeChallenge`, `scopes`, `subject`, and `expiresAt`. So the
+ * adapter hashes to find the row and echoes the presented value back, and a
+ * database dump yields no replayable codes.
+ */
+declare const createAuthCodeStore: ({
+  model
+}: {
+  /** The `OAuthAuthCode` model class, taken from the app's `db` handle. */model: typeof OAuthAuthCode;
+}) => AuthCodeStore;
+//#endregion
+//#region src/stores/createClientStore.d.ts
+/**
+ * Creates a {@link ClientStore} backed by the `oauth_clients` table.
+ *
+ * `register` upserts, so re-registering an existing `client_id` replaces the
+ * stored document rather than failing on the primary key.
+ */
+declare const createClientStore: ({
+  model
+}: {
+  /** The `OAuthClient` model class, taken from the app's `db` handle. */model: typeof OAuthClient;
+}) => ClientStore;
+//#endregion
+//#region src/stores/createRefreshTokenStore.d.ts
+/**
+ * Creates a {@link RefreshTokenStore} backed by the `oauth_refresh_tokens`
+ * table, keyed by token hash and by the `(clientId, subject)` owner that
+ * `deleteByOwner` revokes on reuse detection.
+ */
+declare const createRefreshTokenStore: ({
+  model
+}: {
+  /** The `OAuthRefreshToken` model class, taken from the app's `db` handle. */model: typeof OAuthRefreshToken;
+}) => RefreshTokenStore;
+//#endregion
+export { OAuthAuthCode, OAuthClient, OAuthConsent, type OAuthModels, OAuthRefreshToken, type PostgresdbConsentStore, type PostgresdbOAuthStores, createAuthCodeStore, createClientStore, createConsentStore, createPostgresdbOAuthStores, createRefreshTokenStore, oauthModels };