@udibo/oauth2 0.6.0 → 0.8.0

package/esm/testing/mod.d.ts

@@ -27,10 +27,11 @@
  *   prototypes — never for production.
  *
  * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
- *   protocol surface and its `/api/check` questions over `fetch`, with the
- *   claims a real tenant issues — permissions, the organization picked at
- *   sign-in, and resource grants — so an app built on a Udibo Identity tenant can test
- *   its own routes without running the identity service.
+ *   protocol surface, its `/api/check` questions, and its organization and
+ *   account APIs over `fetch`, with the claims a real tenant issues —
+ *   permissions, the organization picked at sign-in, and resource grants — so
+ *   an app built on a Udibo Identity tenant can test its own routes without
+ *   running the identity service.
  *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.
@@ -40,4 +41,4 @@
 import "../_dnt.polyfills.js";
 export { MemoryAuthorizationCodeService, type MemoryAuthorizationCodeServiceOptions, MemoryClientService, MemoryDeviceAuthorizationService, type MemoryDeviceAuthorizationServiceOptions, MemoryTokenService, type MemoryTokenServiceOptions, MemoryUserService, type MemoryUserServiceOptions, type MemoryUserShape, } from "./services.js";
 export { createMemoryAuthorizationServer, type CreateMemoryAuthorizationServerOptions, type MemoryAuthorizationServerClientSeed, type MemoryAuthorizationServerGrants, type MemoryAuthorizationServerHarness, type MemoryAuthorizationServerUserSeed, } from "./server.js";
-export { createFakeTenant, type FakeTenant, type FakeTenantClient, type FakeTenantGrant, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.js";
+export { createFakeTenant, type FakeTenant, type FakeTenantClient, type FakeTenantGrant, type FakeTenantLinkedAccount, type FakeTenantMembership, type FakeTenantOptions, type FakeTenantOrganization, type FakeTenantOrganizationRole, type FakeTenantSignIn, type FakeTenantSubject, type FakeTenantTokenRequest, type FakeTenantUser, } from "./tenant.js";

package/esm/testing/mod.js

@@ -27,10 +27,11 @@
  *   prototypes — never for production.
  *
  * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
- *   protocol surface and its `/api/check` questions over `fetch`, with the
- *   claims a real tenant issues — permissions, the organization picked at
- *   sign-in, and resource grants — so an app built on a Udibo Identity tenant can test
- *   its own routes without running the identity service.
+ *   protocol surface, its `/api/check` questions, and its organization and
+ *   account APIs over `fetch`, with the claims a real tenant issues —
+ *   permissions, the organization picked at sign-in, and resource grants — so
+ *   an app built on a Udibo Identity tenant can test its own routes without
+ *   running the identity service.
  *
  * Nothing in this module is an OAuth2 primitive — only testing support.
  * Production code should never import from here.

package/esm/testing/tenant.d.ts

@@ -5,14 +5,35 @@ export interface FakeTenantUser {
     id: string;
     /** The `username` introspection reports. */
     username: string;
-    /** The `name` claim UserInfo reports. */
+    /**
+     * The `name` claim UserInfo reports, and the name the organization API's
+     * member listing gives the person. The listing falls back to `username`.
+     */
     name?: string;
-    /** The `email` claim UserInfo reports. */
+    /**
+     * The `email` claim UserInfo reports. An invitation to this address offers
+     * the person a pending membership rather than an invitation.
+     */
     email?: string;
-    /** The `email_verified` claim UserInfo reports. Defaults to `true`. */
+    /**
+     * The `email_verified` claim UserInfo reports. Defaults to `true`. While it
+     * is `false`, invitations to the address stay hidden from the person's
+     * offers and cannot be accepted.
+     */
     emailVerified?: boolean;
     /** Permissions held tenant-wide, in every organization and on every resource. */
     permissions?: string[];
+    /**
+     * The person's own metadata bucket, as `GET /api/account` first reports
+     * it. Defaults to `{}`.
+     */
+    userMetadata?: Record<string, unknown>;
+    /**
+     * Whether the person has a password. Defaults to `true`. Without one, a
+     * linked account is their only way in, and the account API refuses to
+     * disconnect the last of them.
+     */
+    hasPassword?: boolean;
 }
 /** An OAuth2 application registered in a {@linkcode FakeTenant}. */
 export interface FakeTenantClient extends ClientInterface {
@@ -25,6 +46,14 @@ export interface FakeTenantClient extends ClientInterface {
     accessTokenFormat?: "opaque" | "jwt";
     /** A JWT access token's `aud`. Defaults to the client id. */
     audience?: string;
+    /**
+     * Whose application this is. Defaults to `"first-party"`: its credentials
+     * belong to the login session they were issued from, so a later sign-in in
+     * that browser revokes them, revoking one ends the session, and ending the
+     * session revokes them. A `"third-party"` application's credentials only
+     * name that session as the one they came from, and outlive it.
+     */
+    type?: "first-party" | "third-party";
 }
 /** An organization in a {@linkcode FakeTenant}. */
 export interface FakeTenantOrganization {
@@ -38,8 +67,12 @@ export interface FakeTenantOrganization {
 /** A person's place in one organization. */
 export interface FakeTenantMembership {
     /**
-     * The membership's roles, as `org_roles` and `/api/memberships` report
-     * them — `member`, `admin` or `owner` on a real tenant.
+     * The roles the membership holds, as `org_roles`, `/api/memberships` and the
+     * organization API report them. `owner`, `admin` and `member` are the
+     * built-in tiers. `owner` and `admin` may manage the organization through
+     * its API, and only `owner` may delete it or deal in the `owner` tier.
+     * Defaults to `["member"]`, because a membership on a real tenant always
+     * holds a role. An empty list is also read as `["member"]`.
      */
     roles?: string[];
     /** Permissions held inside this organization only. */
@@ -65,6 +98,22 @@ export interface FakeTenantGrant {
     /** What the subject may do on that one resource. */
     permissions: string[];
 }
+/** An organization role your tenant defines beside the built-in tiers. */
+export interface FakeTenantOrganizationRole {
+    /** The role a membership, an invitation or `org_roles` names. */
+    slug: string;
+    /** How the role is named to people. Defaults to the slug. */
+    name?: string;
+}
+/** An external account a person can sign in with. */
+export interface FakeTenantLinkedAccount {
+    /** The provider's key, such as `google` or `github`. */
+    provider: string;
+    /** How the provider is named to the person. Defaults to the key. */
+    displayName?: string;
+    /** The address the provider reported, if any. */
+    email?: string | null;
+}
 /** How the next sign-in resolves. */
 export interface FakeTenantSignIn {
     /**
@@ -77,6 +126,10 @@ export interface FakeTenantSignIn {
      * `invalid_request` when the person is not a member.
      */
     organizationId?: string;
+    /** The browser `GET /api/account/sessions` reports for this sign-in. */
+    userAgent?: string;
+    /** The address `GET /api/account/sessions` reports for this sign-in. */
+    ipAddress?: string;
 }
 /** What {@linkcode FakeTenant.issueAccessToken} mints a token for. */
 export interface FakeTenantTokenRequest {
@@ -105,9 +158,10 @@ export interface FakeTenantOptions {
  * A stand-in for a Udibo Identity tenant, for testing an app that signs in against one
  * without running the identity service. It answers the tenant's protocol
  * surface — discovery, authorize, token, introspection, UserInfo, JWKS — the
- * caller's own `GET /api/memberships`, and the two authorization questions,
- * `POST /api/check` and `POST /api/check/batch`, with the same shapes a real
- * tenant uses.
+ * caller's own `GET /api/memberships`, the two authorization questions,
+ * `POST /api/check` and `POST /api/check/batch`, the organization API under
+ * `/api/organizations`, and the account API under `/api/account`, with the
+ * same shapes and refusals a real tenant uses.
  *
  * Nothing here is interactive: {@linkcode signInAs} decides who the next
  * authorization request authenticates, and there is no consent step. Serve
@@ -125,30 +179,48 @@ export interface FakeTenant {
     /** Adds an organization. Throws on a duplicate id. */
     addOrganization(organization: FakeTenantOrganization): void;
     /**
-     * Makes a person a member of an organization, replacing any earlier
-     * membership. Throws when the organization does not exist.
+     * Makes a person a member of an organization, replacing earlier membership
+     * grants, including pending grants. Email-address invitations remain.
+     * Throws when the organization does not exist.
      */
     addMember(organizationId: string, userId: string, membership?: FakeTenantMembership): void;
     /**
-     * Ends a membership. From then on introspection and `/api/check` stop
-     * answering for that organization on credentials issued in it, and UserInfo
-     * drops its `org_*` claims; a JWT access token or id_token already minted
-     * keeps its claims until it expires.
+     * Ends a membership and removes the person's pending membership grants.
+     * Email-address invitations remain. From then on introspection and
+     * `/api/check` stop answering for that
+     * organization on credentials issued in it, and UserInfo drops its `org_*`
+     * claims; a JWT access token or id_token already minted keeps its claims
+     * until it expires.
      */
     removeMember(organizationId: string, userId: string): void;
+    /**
+     * Defines an organization role beside the built-in tiers, so invitations
+     * may offer it and `member-roles` lists it. Throws on a built-in slug.
+     */
+    defineOrganizationRole(role: FakeTenantOrganizationRole): void;
     /** Registers a resource type, so `/api/check` accepts it. */
     registerResourceType(type: string): void;
     /** Adds a resource grant. */
     grant(grant: FakeTenantGrant): void;
+    /**
+     * Links an external account to a person, as the account API lists it, and
+     * returns its id. Throws when the person does not exist.
+     */
+    linkAccount(userId: string, account: FakeTenantLinkedAccount): string;
     /**
      * Chooses who the next authorization requests authenticate as, until
      * called again. With nobody chosen, authorize answers `access_denied`.
+     *
+     * Each call is a new browser: the first authorization after it starts a
+     * login session, which the account API lists, and later ones reuse it until
+     * that session is ended. When a first-party application signs in again in
+     * that browser, the credentials the session issued before are revoked.
      */
     signInAs(userId: string | null, signIn?: FakeTenantSignIn): void;
     /**
      * Mints an access token without the browser flow, for testing an API
-     * directly. JWT or opaque as the client is registered. Throws when the
-     * client or user does not exist.
+     * directly. JWT or opaque as the client is registered. It belongs to no
+     * login session. Throws when the client or user does not exist.
      */
     issueAccessToken(request: FakeTenantTokenRequest): Promise<string>;
 }