@dereekb/firebase 13.28.0 → 13.30.0

package/src/lib/common/auth/oidc/oidc.d.ts

@@ -1,5 +1,6 @@
 import { type LabeledValueWithDescription, type Maybe } from '@dereekb/util';
 import { type KnownOnCallFunctionType, type OnCallFunctionType } from '../../model/function';
+import { type OidcScope } from './oidc.base';
 /**
  * Prefix shared by every callModel OIDC scope (e.g., `model.create`).
  *
@@ -125,3 +126,138 @@ export type ServiceTokenOidcScope = typeof SERVICE_TOKEN_OIDC_SCOPE;
  * restricted to privileged users.
  */
 export declare const SERVICE_TOKEN_OIDC_SCOPE_DETAILS: LabeledValueWithDescription<ServiceTokenOidcScope>;
+/**
+ * A single requirement TERM in the callModel OIDC scope model.
+ *
+ * A term is satisfied when the caller holds the required scope(s):
+ * - a single {@link OidcScope} — the caller must hold exactly that scope; or
+ * - a `readonly` array of {@link OidcScope}s — an OR-group the caller satisfies by holding ANY one
+ *   (an empty group imposes no requirement).
+ *
+ * Multiple terms combine with AND — see {@link oidcScopeTermsSatisfied}. The callModel gate ANDs the
+ * per-verb `model.<call>` scope with the effective GROUP term resolved for the model/handler.
+ */
+export type OidcScopeTerm = OidcScope | readonly OidcScope[];
+/**
+ * Parses a raw OIDC `scope` claim (a space-delimited string) into the granted scope set consumed by
+ * {@link oidcScopeTermSatisfied} / {@link oidcScopeTermsSatisfied}.
+ *
+ * The single source of truth for scope-string parsing, shared by the server-side `getOidcScopesFromRequest`
+ * (which reads `request.auth.token.scope`) and the model-api-layer enforcement (which reads the OIDC-validated
+ * token off the request auth). Returns `undefined` when the claim is not a string — i.e. the caller is not
+ * OIDC-authenticated (a regular Firebase ID token carries no `scope` claim) — so callers can distinguish
+ * "no OIDC scopes to enforce against" (bypass) from "OIDC caller that was granted zero scopes" (empty set).
+ *
+ * @param scope - The raw `scope` claim value, typically a space-delimited string.
+ * @returns A `Set` of the granted scopes, or `undefined` when `scope` is not a string.
+ */
+export declare function oidcScopesFromScopeClaim(scope: unknown): Maybe<Set<OidcScope>>;
+/**
+ * Verb-keyed form of {@link OidcModelScopeRequirement}: a term per {@link OnCallFunctionType}, with an
+ * optional `default` term applied to verbs without an explicit entry.
+ */
+export interface OidcModelScopeRequirementVerbMap {
+    /**
+     * Fallback term applied to any verb without an explicit entry below.
+     */
+    readonly default?: OidcScopeTerm;
+    /**
+     * Per-verb term keyed by call type (e.g. `read`, `create`, `query`). A `read` entry is the only
+     * way to require a scope on a PLAIN READ, which has no per-function handler.
+     */
+    readonly [verb: string]: OidcScopeTerm | undefined;
+}
+/**
+ * Per-model callModel scope requirement, consulted by the model-api scope gate and the MCP visibility filter.
+ *
+ * Either a single {@link OidcScopeTerm} applied to EVERY verb, or an {@link OidcModelScopeRequirementVerbMap}
+ * (verb-keyed with an optional `default`). The verb-keyed form is the only way to require a scope on
+ * a plain read — a plain read has no per-function handler to hang a `requiredScope` on, but the
+ * scope gate still resolves its verb + model type, so a `read` entry here reaches it.
+ *
+ * @example
+ * ```typescript
+ * // WorkerAcademyProgress is wholly LMS — same term for every verb:
+ * const wap: OidcModelScopeRequirement = ['hellosubs', 'lms'];
+ * // allow lms reads, require hellosubs for everything else:
+ * const worker: OidcModelScopeRequirement = { read: ['hellosubs', 'lms'], default: 'hellosubs' };
+ * ```
+ */
+export type OidcModelScopeRequirement = OidcScopeTerm | OidcModelScopeRequirementVerbMap;
+/**
+ * Returns whether a single {@link OidcScopeTerm} is satisfied by the granted scope set.
+ *
+ * A string term requires that exact scope; an array term is an OR-group satisfied by ANY member (an
+ * empty group is vacuously satisfied — no requirement).
+ *
+ * @param term - The scope term to test.
+ * @param grantedScopes - The scopes the caller holds.
+ * @returns `true` when the caller satisfies the term.
+ */
+export declare function oidcScopeTermSatisfied(term: OidcScopeTerm, grantedScopes: ReadonlySet<OidcScope>): boolean;
+/**
+ * Returns whether EVERY {@link OidcScopeTerm} is satisfied by the granted scope set (AND-of-ORs).
+ *
+ * The single source of truth shared by the server-side callModel scope enforcement
+ * (`assertModelApiOidcScope`) and the MCP tool-visibility filter, so enforcement and tool-list
+ * visibility never drift. An empty term list is vacuously satisfied.
+ *
+ * @param terms - The AND-ed scope terms; each is a single scope or an OR-group.
+ * @param grantedScopes - The scopes the caller holds.
+ * @returns `true` when the caller satisfies every term.
+ */
+export declare function oidcScopeTermsSatisfied(terms: readonly OidcScopeTerm[], grantedScopes: ReadonlySet<OidcScope>): boolean;
+/**
+ * Resolves the effective {@link OidcScopeTerm} an {@link OidcModelScopeRequirement} imposes for a
+ * given call verb.
+ *
+ * A single-term requirement applies to every verb; a verb-keyed requirement returns the matching
+ * verb entry, falling back to its `default`. Returns `undefined` when the requirement imposes no
+ * term for the verb.
+ *
+ * @param requirement - The per-model requirement.
+ * @param call - The call verb being resolved.
+ * @returns The effective term for the verb, or `undefined`.
+ */
+export declare function resolveOidcModelScopeRequirement(requirement: OidcModelScopeRequirement, call: OnCallFunctionType): Maybe<OidcScopeTerm>;
+/**
+ * Inputs to {@link resolveEffectiveOidcScopeTerms}.
+ */
+export interface ResolveEffectiveOidcScopeTermsInput {
+    /**
+     * The per-verb `model.<call>` scope, if any — kept as its own AND term.
+     */
+    readonly perVerbScope?: Maybe<OidcScopeTerm>;
+    /**
+     * The per-function `requiredScope` from `withApiDetails`, if any — the finest (highest-precedence)
+     * group term.
+     */
+    readonly requiredScope?: Maybe<OidcScopeTerm>;
+    /**
+     * The model-level requirement for the targeted model type, if configured.
+     */
+    readonly modelRequirement?: Maybe<OidcModelScopeRequirement>;
+    /**
+     * The call verb, used to resolve a verb-keyed {@link modelRequirement}.
+     */
+    readonly call: OnCallFunctionType;
+    /**
+     * The configured default group term applied when no finer term overrides it.
+     */
+    readonly defaultRequiredScope?: Maybe<OidcScopeTerm>;
+}
+/**
+ * Resolves the full AND-ed list of {@link OidcScopeTerm}s enforced for one callModel op — the single
+ * composition rule shared by the server model-api scope gate and the MCP visibility filter (no drift).
+ *
+ * The list is the per-verb scope AND the effective GROUP term, where the group term is resolved by
+ * precedence: per-function `requiredScope` (finest) > model-level requirement (verb-resolved; covers
+ * plain reads) > configured default. Nullish and empty-OR-group terms are dropped, so an op with no
+ * requirement yields an empty list (no scope gate — the caller can skip reading scopes). With no
+ * config supplied and no per-function scope, the list is exactly `[perVerbScope]` (or empty), matching
+ * the pre-grouping behavior.
+ *
+ * @param input - The per-verb scope, per-function scope, model requirement, verb, and default.
+ * @returns The AND-ed scope terms to enforce (possibly empty).
+ */
+export declare function resolveEffectiveOidcScopeTerms(input: ResolveEffectiveOidcScopeTermsInput): OidcScopeTerm[];

package/src/lib/{model/oidcmodel/oidcmodel.interaction.oauth.d.ts → common/auth/oidc/oidc.interaction.d.ts}

@@ -1,7 +1,6 @@
 import { type Maybe, type SpaceSeparatedString, type WebsiteUrlWithPrefix } from '@dereekb/util';
-import { type FirebaseAuthIdToken } from '../../common/auth/auth';
-import { type OidcEntryClientId } from './oidcmodel.id';
-import { type OidcScope } from './oidcmodel.interaction';
+import { type FirebaseAuthIdToken } from '../auth';
+import { type OidcEntryClientId, type OidcScope } from './oidc.base';
 /**
  * Request body sent by the frontend to complete a login interaction.
  *
@@ -30,6 +29,12 @@ export interface OAuthInteractionLoginDetails<T extends OidcScope = OidcScope> {
     readonly logo_uri?: Maybe<string>;
     readonly client_uri?: Maybe<string>;
     readonly scopes: OAuthInteractionScopes<T>;
+    /**
+     * Space-separated subset of `scopes` the client's assigned provider profiles force-require. The
+     * consent UI renders these as required (pre-checked, non-deselectable); the server force-grants
+     * them. Absent/empty when the client requires no profile scopes.
+     */
+    readonly requiredScopes?: OAuthInteractionScopes<T>;
 }
 /**
  * Response from the server after a successful interaction submission.

package/src/lib/common/auth/oidc/oidc.profile.d.ts

@@ -0,0 +1,107 @@
+import { type LabeledValueWithDescription } from '@dereekb/util';
+import { type OidcScope } from './oidc.base';
+/**
+ * Arbitrary key identifying an {@link OidcProviderProfile} (e.g. `'lms'`).
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:oidc
+ */
+export type OidcProviderProfileKey = string;
+/**
+ * How a scope unlocked by an {@link OidcProviderProfile} is enforced for a client
+ * carrying that profile.
+ *
+ * - `none`: the scope is merely unlocked/allowed — the client may request it, but it stays optional.
+ * - `required`: the scope is force-required — it is surfaced as a required (non-deselectable) scope
+ *   at consent and the interaction is rejected if it is not granted.
+ */
+export type OidcProviderProfileScopeRequireMode = 'none' | 'required';
+/**
+ * A single scope entry within an {@link OidcProviderProfile}.
+ */
+export interface OidcProviderProfileScopeConfig<S extends OidcScope = OidcScope> {
+    /**
+     * The scope this profile unlocks. It should be a scope that is otherwise restricted (not offered
+     * in the general scope picker) so that only clients carrying this profile can request it.
+     */
+    readonly scope: S;
+    /**
+     * How the scope is enforced. Defaults to `none` (unlock only, optional) when omitted.
+     */
+    readonly require?: OidcProviderProfileScopeRequireMode;
+}
+/**
+ * A named, admin-assignable preset that unlocks (and optionally force-requires) scopes for the OIDC
+ * clients it is assigned to.
+ *
+ * Provider profiles are declared statically in code (an exported registry) and supplied to the
+ * provider via {@link OidcProviderConfig.providerProfiles}. An admin assigns one or more profile keys
+ * to an OIDC client (persisted as `dbx_provider_profiles` client metadata). At consent, a scope
+ * referenced by any profile is treated as restricted: a client may only obtain it when one of its
+ * assigned profiles unlocks it.
+ *
+ * @example
+ * ```ts
+ * const LMS_PROVIDER_PROFILE: OidcProviderProfile = {
+ *   key: 'lms',
+ *   label: 'LMS',
+ *   scopes: [{ scope: 'lms', require: 'required' }]
+ * };
+ * ```
+ */
+export interface OidcProviderProfile<S extends OidcScope = OidcScope> {
+    /**
+     * Unique key for the profile (e.g. `'lms'`).
+     */
+    readonly key: OidcProviderProfileKey;
+    /**
+     * Human-readable label, used in the admin profile picker.
+     */
+    readonly label: string;
+    /**
+     * Optional human-readable description, used in the admin profile picker.
+     */
+    readonly description?: string;
+    /**
+     * The scopes this profile unlocks, each with an optional require mode.
+     */
+    readonly scopes: readonly OidcProviderProfileScopeConfig<S>[];
+}
+/**
+ * Profile picker entry (label + key + description), mirroring {@link OidcScopeDetails}.
+ */
+export type OidcProviderProfileDetails = LabeledValueWithDescription<OidcProviderProfileKey>;
+/**
+ * Filters the provider-profile registry to the profiles matching the given assigned keys.
+ *
+ * @param profiles - The full provider-profile registry.
+ * @param keys - The profile keys assigned to a client (e.g. `OidcEntry` `dbx_provider_profiles`).
+ * @returns The registry profiles whose key is in `keys`.
+ */
+export declare function oidcProviderProfilesForKeys<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[], keys: readonly OidcProviderProfileKey[] | undefined): OidcProviderProfile<S>[];
+/**
+ * Collects every scope referenced by the given profiles.
+ *
+ * Passed the full registry, this is the set of "profile-gated" scopes — scopes a client may only
+ * obtain via a profile. Passed a client's assigned profiles, this is the set of scopes those
+ * profiles unlock for that client.
+ *
+ * @param profiles - The profiles to collect scopes from.
+ * @returns The union of every profile's scopes.
+ */
+export declare function scopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
+/**
+ * Collects the scopes marked `require: 'required'` across the given profiles.
+ *
+ * @param profiles - The profiles to collect required scopes from (typically a client's assigned profiles).
+ * @returns The union of every profile's `required` scopes.
+ */
+export declare function requiredScopesForOidcProviderProfiles<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): Set<S>;
+/**
+ * Builds picker entries for the given provider profiles, suitable for an admin profile-selection field.
+ *
+ * @param profiles - The provider-profile registry.
+ * @returns One {@link OidcProviderProfileDetails} per profile.
+ */
+export declare function oidcProviderProfileDetails<S extends OidcScope = OidcScope>(profiles: readonly OidcProviderProfile<S>[]): OidcProviderProfileDetails[];

package/src/lib/model/oidcmodel/index.d.ts

@@ -4,5 +4,3 @@ export * from './oidcmodel.query';
 export * from './oidcmodel.api';
 export * from './oidcmodel.action';
 export * from './oidcmodel.data';
-export * from './oidcmodel.interaction';
-export * from './oidcmodel.interaction.oauth';

package/src/lib/model/oidcmodel/oidcmodel.api.d.ts

@@ -1,11 +1,9 @@
 import { type Type } from 'arktype';
-import { type TargetModelParams, type OnCallCreateModelResult } from '../../common';
+import { type TargetModelParams, type OnCallCreateModelResult, type OidcEntryClientId, type OidcRedirectUri, type OidcTokenEndpointAuthMethod } from '../../common';
 import { type InferredTargetModelParams } from '../../common/model/model/model.param';
 import { type ModelFirebaseCrudFunction, type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap, type ModelFirebaseCreateFunction, type ModelFirebaseDeleteFunction, type ModelFirebaseUpdateFunction } from '../../client';
 import { type WebsiteUrlWithPrefix, type Maybe } from '@dereekb/util';
-import { type OidcEntryClientId } from './oidcmodel.id';
 import { type OidcModelTypes } from './oidcmodel';
-import { type OidcRedirectUri, type OidcTokenEndpointAuthMethod } from './oidcmodel.interaction';
 /**
  * Fields that can be changed on an existing OIDC client.
  *
@@ -25,6 +23,13 @@ export interface UpdateOidcClientFieldParams {
      * Set to `null` to clear an existing value.
      */
     readonly dbx_max_session_ttl?: Maybe<number>;
+    /**
+     * OIDC provider profile keys assigned to this client (unlock/force-require otherwise-restricted
+     * scopes). Admin-only: stripped from non-admin create/update requests before the action runs.
+     *
+     * Set to `null` (or `[]`) to clear the assignment.
+     */
+    readonly dbx_provider_profiles?: Maybe<string[]>;
 }
 export declare const updateOidcClientFieldParamsType: Type<UpdateOidcClientFieldParams>;
 export declare const createOidcClientFieldParamsType: import("arktype/internal/variants/object.ts").ObjectType<{
@@ -33,7 +38,8 @@ export declare const createOidcClientFieldParamsType: import("arktype/internal/v
     readonly logo_uri?: Maybe<string>;
     readonly client_uri?: Maybe<string>;
     readonly dbx_max_session_ttl?: Maybe<number>;
-    token_endpoint_auth_method: "none" | "client_secret_basic" | "client_secret_post" | "client_secret_jwt" | "private_key_jwt";
+    readonly dbx_provider_profiles?: Maybe<string[]>;
+    token_endpoint_auth_method: "client_secret_basic" | "client_secret_post" | "client_secret_jwt" | "private_key_jwt" | "none";
 }, {}>;
 /**
  * Parameters for registering a new OAuth client for the target entity.

package/src/lib/model/oidcmodel/oidcmodel.data.d.ts

@@ -1,6 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type OidcEntryClientId } from './oidcmodel.id';
-import { type OidcRedirectUri } from './oidcmodel.interaction';
+import { type OidcEntryClientId, type OidcRedirectUri } from '../../common';
 /**
  * Corresponds with readable content from a OidcEntry's payload.
  */
@@ -21,6 +20,14 @@ export interface OidcEntryOAuthClientPayloadData {
      * Caps how long a client may request via the `dbx_session_ttl` auth-URL param.
      */
     readonly dbx_max_session_ttl?: Maybe<number>;
+    /**
+     * Optional OIDC provider profile keys assigned to this client.
+     *
+     * Custom oidc-provider client metadata (registered via `extraClientMetadata`). Each key references
+     * an {@link OidcProviderProfile} that unlocks (and optionally force-requires) otherwise-restricted
+     * scopes for this client. Admin-only: stripped from non-admin create/update requests.
+     */
+    readonly dbx_provider_profiles?: Maybe<string[]>;
 }
 /**
  * Subset of an oidc-provider Grant adapter payload that is safe to expose to the

package/src/lib/model/oidcmodel/oidcmodel.id.d.ts

@@ -12,12 +12,3 @@ export type OidcEntryId = FirestoreModelId;
  * Full Firestore model key path for an OidcEntry document.
  */
 export type OidcEntryKey = FirestoreModelKey;
-/**
- * Unique client identifier for an OIDC client registration.
- *
- * @semanticType
- * @semanticTopic identifier
- * @semanticTopic string
- * @semanticTopic dereekb-firebase:oidc
- */
-export type OidcEntryClientId = string;

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.28.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/date": "13.28.0",
-    "@dereekb/firebase": "13.28.0",
-    "@dereekb/model": "13.28.0",
-    "@dereekb/rxjs": "13.28.0",
-    "@dereekb/util": "13.28.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",