@structured-id/ui-core 1.2.0 → 2.0.0

package/src/profile/composables/useAuthApi.ts

@@ -1,15 +1,20 @@
 /**
  * Profile auth API composable.
  *
- * Wraps AuthServiceClient proto calls with Bearer auth.
  * Covers: OPAQUE, MFA, step-up, WebAuthn, magic link, OAuth2, CIBA, captcha, terms.
  *
- * OPAQUE gRPC calls are here (like all other auth RPCs).
- * OPAQUE client-side crypto orchestration lives in useOpaqueAuth.ts
- * (accepts OpaqueClientApi interface — no dependency on @structured-id/opaque).
+ * Two surfaces: sign-in ceremonies go to SID's sign-in surface
+ * (`getTransport`), where the IdP session lives; managing the signed-in
+ * user's factors from the account pages is the account API
+ * (`getAccountTransport`), through the BFF.
+ *
+ * OPAQUE gRPC calls are here (like all other auth RPCs). The password
+ * ceremonies over them (client-side crypto, proofs) live in useAuth.ts,
+ * behind the injected ZkppClientApi: no dependency on the client package.
  */
 import {
   getTransport,
+  getAccountTransport,
   AuthServiceClient,
   StepUpMethod,
   type OpaqueLoginStartResponse,
@@ -48,17 +53,43 @@ import {
   type RequestPasswordResetResponse,
   type VerifyPasswordResetResponse,
   type CompletePasswordResetResponse,
+  type ExecutePasswordResetResponse,
+  type OpaqueZkppRegistrationStartResponse,
+  type OpaqueZkppRegistrationFinishResponse,
+  type PasswordChangeChallengeResponse,
+  type PasswordChangeExecuteResponse,
+  type PasswordChangeFinishResponse,
+  type PasswordHistoryContext,
+  type PasswordHistoryEvaluation,
+  type PasswordRegistrationProof,
+  PasswordHistoryEvaluatorServiceClient,
 } from "../../index";
 import { authMeta } from "../auth";
 
+/** The history evaluator: in CE served beside the credential service. */
+function evaluator(): PasswordHistoryEvaluatorServiceClient {
+  return new PasswordHistoryEvaluatorServiceClient(getTransport());
+}
+
+/** The wire form of an operation id (16 UUIDv7 bytes). */
+function operation(id: Uint8Array): { value: Uint8Array } {
+  return { value: id };
+}
+
+/** The sign-in surface: ceremonies and the IdP session. */
 function client(): AuthServiceClient {
   return new AuthServiceClient(getTransport());
 }
 
+/** The account API: the signed-in user managing their own factors. */
+function account(): AuthServiceClient {
+  return new AuthServiceClient(getAccountTransport());
+}
+
 // ── MFA TOTP ──
 
 export async function startTotpEnrollment(): Promise<TotpEnrollmentChallenge> {
-  const { response } = await client().startTotpEnrollment(
+  const { response } = await account().startTotpEnrollment(
     {},
     { meta: authMeta() },
   );
@@ -68,7 +99,7 @@ export async function startTotpEnrollment(): Promise<TotpEnrollmentChallenge> {
 export async function finishTotpEnrollment(
   code: string,
 ): Promise<FinishTotpEnrollmentResponse> {
-  const { response } = await client().finishTotpEnrollment(
+  const { response } = await account().finishTotpEnrollment(
     { code },
     { meta: authMeta() },
   );
@@ -101,7 +132,7 @@ export async function resendSmsMfa(): Promise<ResendSmsMfaResponse> {
 // ── MFA Recovery ──
 
 export async function generateRecoveryCodes(): Promise<GenerateRecoveryCodesResponse> {
-  const { response } = await client().generateRecoveryCodes(
+  const { response } = await account().generateRecoveryCodes(
     {},
     { meta: authMeta() },
   );
@@ -199,7 +230,7 @@ export async function webAuthnAuthenticationFinish(
 export async function webAuthnRegistrationStart(
   label?: string,
 ): Promise<WebAuthnRegistrationStartResponse> {
-  const { response } = await client().webAuthnRegistrationStart(
+  const { response } = await account().webAuthnRegistrationStart(
     { label },
     { meta: authMeta() },
   );
@@ -210,7 +241,7 @@ export async function webAuthnRegistrationFinish(
   credential: Uint8Array,
   label?: string,
 ): Promise<WebAuthnRegistrationFinishResponse> {
-  const { response } = await client().webAuthnRegistrationFinish(
+  const { response } = await account().webAuthnRegistrationFinish(
     { credential, label },
     { meta: authMeta() },
   );
@@ -241,6 +272,10 @@ export async function oauth2Authorize(params: {
   codeChallenge?: string;
   codeChallengeMethod?: string;
   nonce?: string;
+  /** Issuer of the authorization request being completed (`/i/<handle>/oauth2/authorize`). */
+  issuerHandle: string;
+  /** RFC 8707 resource indicators of the request; empty selects the client's default. */
+  resource?: string[];
 }): Promise<{ authorizationCode?: string; error?: string; state?: string }> {
   const { response } = await client().oAuth2Authorize(
     {
@@ -252,6 +287,8 @@ export async function oauth2Authorize(params: {
       codeChallenge: params.codeChallenge,
       codeChallengeMethod: params.codeChallengeMethod,
       nonce: params.nonce,
+      issuerHandle: params.issuerHandle,
+      resource: params.resource ?? [],
     },
     { meta: authMeta() },
   );
@@ -455,7 +492,7 @@ export async function completeStepUp(
 export async function deleteMfaCredential(
   credentialId: string,
 ): Promise<DeleteMfaCredentialResponse> {
-  const { response } = await client().deleteMfaCredential(
+  const { response } = await account().deleteMfaCredential(
     { credentialId },
     { meta: authMeta() },
   );
@@ -502,23 +539,37 @@ export async function verifyPasswordReset(
   return response;
 }
 
+/**
+ * The OPAQUE start of the replacement password under the reset's operation
+ * (from `VerifyPasswordResetResponse.history`).
+ */
+export async function executePasswordReset(
+  operationId: Uint8Array,
+  registrationRequest: Uint8Array,
+): Promise<ExecutePasswordResetResponse> {
+  const { response } = await client().executePasswordReset({
+    operationId: operation(operationId),
+    registrationRequest,
+  });
+  return response;
+}
+
+/**
+ * Complete the reset with the replacement password's record and, when the
+ * client proved it, the proof; without a proof the password installs
+ * policy-unverified.
+ */
 export async function completePasswordReset(
   resetSessionId: string,
+  operationId: Uint8Array,
   registrationRecord: Uint8Array,
-  opts?: {
-    zkppProof?: Uint8Array;
-    zkppInstances?: Uint8Array[];
-    historyCommitment?: Uint8Array;
-    commitmentSalt?: Uint8Array;
-  },
+  proof?: PasswordRegistrationProof,
 ): Promise<CompletePasswordResetResponse> {
   const { response } = await client().completePasswordReset({
     resetSessionId,
+    operationId: operation(operationId),
     registrationRecord,
-    zkppProof: opts?.zkppProof ?? new Uint8Array(),
-    zkppInstances: opts?.zkppInstances ?? [],
-    historyCommitment: opts?.historyCommitment ?? new Uint8Array(),
-    commitmentSalt: opts?.commitmentSalt ?? new Uint8Array(),
+    proof,
   });
   return response;
 }
@@ -526,6 +577,107 @@ export async function completePasswordReset(
 // Recovery shard RPCs (downloadRecoveryShard, uploadRecoveryShard, getRecoveryInfo)
 // are EE/SaaS-only — defined in proto-ee, not in CE proto.
 
+// ── Password operations (OPAQUE-ZKPP) ──
+//
+// Registration, password change and reset install a password in one
+// server-side operation: the preparing RPC returns the operation's history
+// context, the evaluator answers the client's blinded history input, the
+// client proves, and the finish carries the record with the proof.
+
+/**
+ * Start a registration: the operation is prepared for the new account and its
+ * OPAQUE request answered. `claimToken` claims an installation that has no
+ * administrator yet.
+ */
+export async function opaqueZkppRegistrationStart(
+  principal: string,
+  registrationRequest: Uint8Array,
+  claimToken?: string,
+): Promise<OpaqueZkppRegistrationStartResponse> {
+  const { response } = await client().opaqueZkppRegistrationStart({
+    principal,
+    registrationRequest,
+    claimToken,
+  });
+  return response;
+}
+
+/** Finish a registration with the record and, when the client proved, the proof. */
+export async function opaqueZkppRegistrationFinish(
+  operationId: Uint8Array,
+  registrationRecord: Uint8Array,
+  proof?: PasswordRegistrationProof,
+): Promise<OpaqueZkppRegistrationFinishResponse> {
+  const { response } = await client().opaqueZkppRegistrationFinish({
+    operationId: operation(operationId),
+    registrationRecord,
+    proof,
+  });
+  return response;
+}
+
+/**
+ * The evaluator's answers to the blinded history input of the operation:
+ * one per comparison domain of its context, in that order.
+ */
+export async function evaluatePasswordHistory(
+  operationId: Uint8Array,
+  blindedInput: Uint8Array,
+): Promise<PasswordHistoryEvaluation[]> {
+  const { response } = await evaluator().evaluatePasswordHistory({
+    operationId: operation(operationId),
+    blindedInput,
+  });
+  return response.evaluations;
+}
+
+/** Prepare a change of the signed-in user's own password `credentialId`. */
+export async function passwordChangeChallenge(
+  credentialId: string,
+): Promise<PasswordChangeChallengeResponse> {
+  const { response } = await account().passwordChangeChallenge(
+    { credentialId },
+    { meta: authMeta() },
+  );
+  return response;
+}
+
+/** The OPAQUE start of the new password under the change's operation. */
+export async function passwordChangeExecute(
+  operationId: Uint8Array,
+  credentialId: string,
+  registrationRequest: Uint8Array,
+): Promise<PasswordChangeExecuteResponse> {
+  const { response } = await account().passwordChangeExecute(
+    {
+      operationId: operation(operationId),
+      credentialId,
+      registrationRequest,
+    },
+    { meta: authMeta() },
+  );
+  return response;
+}
+
+/** Finish the change with the new password's record and, when proved, the proof. */
+export async function passwordChangeFinish(
+  operationId: Uint8Array,
+  credentialId: string,
+  registrationRecord: Uint8Array,
+  proof?: PasswordRegistrationProof,
+): Promise<PasswordChangeFinishResponse> {
+  const { response } = await account().passwordChangeFinish(
+    {
+      operationId: operation(operationId),
+      credentialId,
+      registrationRecord,
+      proof,
+    },
+    { meta: authMeta() },
+  );
+  return response;
+}
+
 // ── OPAQUE ──
 
 export async function opaqueLoginStart(
@@ -552,13 +704,20 @@ export async function opaqueLoginFinish(
   return response;
 }
 
+/**
+ * `claimToken`: the instance claim token (`sidclaim_...`) from the service log.
+ * Required while the installation has no administrator; the new profile then
+ * becomes its first administrator.
+ */
 export async function opaqueRegistrationStart(
   principal: string,
   registrationRequest: Uint8Array,
+  claimToken?: string,
 ): Promise<OpaqueRegistrationStartResponse> {
   const { response } = await client().opaqueRegistrationStart({
     principal,
     registrationRequest,
+    claimToken,
   });
   return response;
 }
@@ -613,5 +772,14 @@ export type {
   VerifyMagicLinkResponse,
   RequestPasswordResetResponse,
   VerifyPasswordResetResponse,
+  ExecutePasswordResetResponse,
   CompletePasswordResetResponse,
+  OpaqueZkppRegistrationStartResponse,
+  OpaqueZkppRegistrationFinishResponse,
+  PasswordChangeChallengeResponse,
+  PasswordChangeExecuteResponse,
+  PasswordChangeFinishResponse,
+  PasswordHistoryContext,
+  PasswordHistoryEvaluation,
+  PasswordRegistrationProof,
 };

package/src/profile/composables/useEnrollmentApi.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getInstanceStatus } from "./useEnrollmentApi";
+
+const mockGetInstanceStatus = vi.fn();
+
+vi.mock("../../index", () => ({
+  getTransport: vi.fn(),
+  EnrollmentServiceClient: vi.fn().mockImplementation(() => ({
+    getInstanceStatus: mockGetInstanceStatus,
+  })),
+}));
+
+describe("getInstanceStatus", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // The registration page asks before anyone signs in, so the call must
+  // carry no credentials and return the server's answer as is.
+  it("asks without credentials and returns the status", async () => {
+    mockGetInstanceStatus.mockResolvedValue({ response: { claimed: false } });
+
+    const status = await getInstanceStatus();
+
+    expect(mockGetInstanceStatus).toHaveBeenCalledWith({});
+    expect(status).toEqual({ claimed: false });
+  });
+
+  it("propagates gRPC errors", async () => {
+    mockGetInstanceStatus.mockRejectedValue(new Error("UNAVAILABLE"));
+    await expect(getInstanceStatus()).rejects.toThrow("UNAVAILABLE");
+  });
+});

package/src/profile/composables/useEnrollmentApi.ts

@@ -0,0 +1,26 @@
+/**
+ * Profile enrollment API composable.
+ *
+ * Wraps the public EnrollmentServiceClient calls the registration page makes
+ * before anyone signs in.
+ */
+import {
+  getTransport,
+  EnrollmentServiceClient,
+  type InstanceStatus,
+} from "../../index";
+
+function client(): EnrollmentServiceClient {
+  return new EnrollmentServiceClient(getTransport());
+}
+
+export type { InstanceStatus };
+
+/**
+ * Whether the installation has its first administrator. While it has none,
+ * registration accepts only the claim token from the service log.
+ */
+export async function getInstanceStatus(): Promise<InstanceStatus> {
+  const { response } = await client().getInstanceStatus({});
+  return response;
+}

package/src/profile/composables/useIdentityApi.ts

@@ -1,11 +1,13 @@
 /**
  * Profile identity API composable.
  *
- * Wraps IdentityServiceClient proto calls with Bearer auth.
- * Shared between profile-ui-ce, profile-ui-ee, and frontend.
+ * The account API through the BFF (`getAccountTransport`), which adds the
+ * session's Bearer token. Shared between profile-ui-ce, profile-ui-ee, and
+ * frontend.
  */
+import type { RpcTransport } from "@protobuf-ts/runtime-rpc";
 import {
-  getTransport,
+  getAccountTransport,
   IdentityServiceClient,
   type Profile,
   type Session,
@@ -19,8 +21,8 @@ import {
 } from "../../index";
 import { authMeta } from "../auth";
 
-function client(): IdentityServiceClient {
-  return new IdentityServiceClient(getTransport());
+function client(transport?: RpcTransport): IdentityServiceClient {
+  return new IdentityServiceClient(transport ?? getAccountTransport());
 }
 
 // ── Profile ──
@@ -28,10 +30,17 @@ function client(): IdentityServiceClient {
 export type { Profile, Principal };
 
 export async function fetchCurrentProfile(): Promise<Profile> {
-  const { response } = await client().getCurrentProfile({}, { meta: authMeta() });
+  const { response } = await client().getCurrentProfile(
+    {},
+    { meta: authMeta() },
+  );
   return response.profile!;
 }
 
+/**
+ * `transport`: the sign-in surface's transport when a sign-in step (a
+ * required profile update) makes the call; the account API otherwise.
+ */
 export async function updateProfile(
   id: string,
   update: {
@@ -40,8 +49,9 @@ export async function updateProfile(
     middleName?: string;
     avatarUrl?: string;
   },
+  transport?: RpcTransport,
 ): Promise<Profile> {
-  const { response } = await client().updateProfile(
+  const { response } = await client(transport).updateProfile(
     {
       id,
       givenName: update.givenName,

package/src/profile/composables/useLoginSuccess.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { setActivePinia, createPinia } from "pinia";
 import { createApp, defineComponent } from "vue";
 import { createRouter, createMemoryHistory } from "vue-router";
-import { useLoginSuccess } from "./useLoginSuccess";
+import { authorizationContinuation, useLoginSuccess } from "./useLoginSuccess";
 import { useAuthStore } from "../../stores/auth";
 
 // Mock checkBffSession from BFF composable
@@ -13,19 +13,22 @@ vi.mock("../../composables/useBffAuth", () => ({
 import { checkBffSession } from "../../composables/useBffAuth";
 const mockCheckBffSession = vi.mocked(checkBffSession);
 
-// Helper: run composable inside a real Vue app with router + pinia
+// Helper: run composable inside a real Vue app with router + pinia, the
+// current route at `at`.
 async function withApp<T>(
   fn: () => T,
+  at = "/",
 ): Promise<{ result: T; router: ReturnType<typeof createRouter> }> {
   const router = createRouter({
     history: createMemoryHistory(),
     routes: [
       { path: "/", component: { template: "<div />" } },
+      { path: "/login", component: { template: "<div />" } },
       { path: "/account", component: { template: "<div />" } },
       { path: "/admin", component: { template: "<div />" } },
     ],
   });
-  await router.push("/");
+  await router.push(at);
   await router.isReady();
 
   const pinia = createPinia();
@@ -47,6 +50,50 @@ async function withApp<T>(
   return { result: result!, router };
 }
 
+const ISSUER = "https://sid.example.com";
+const HANDLE = "0123456789abcdef0123456789abcdef";
+const CONTINUATION = `${ISSUER}/i/${HANDLE}/oauth2/authorize?client_id=app&request_uri=${encodeURIComponent("urn:ietf:params:oauth:request_uri:ref_1")}`;
+
+describe("authorizationContinuation", () => {
+  it("accepts the continuation of a request at the issuer", () => {
+    expect(authorizationContinuation(CONTINUATION, ISSUER)).toBe(CONTINUATION);
+    // The origin may be given as any URL of the installation.
+    expect(authorizationContinuation(CONTINUATION, `${ISSUER}/account`)).toBe(
+      CONTINUATION,
+    );
+  });
+
+  // Each substitution an attacker could make in `rd` is refused: another
+  // origin, scheme or port, credentials, a fragment, another path, a full
+  // request instead of a reference, extra or missing parameters.
+  it("refuses everything else", () => {
+    const ref = encodeURIComponent("urn:ietf:params:oauth:request_uri:ref_1");
+    const at = (base: string) =>
+      `${base}/i/${HANDLE}/oauth2/authorize?client_id=app&request_uri=${ref}`;
+    for (const rd of [
+      undefined,
+      ["x"],
+      "",
+      "not a url",
+      "javascript:alert(1)",
+      at("https://evil.example.com"),
+      at("http://sid.example.com"),
+      at("https://sid.example.com:8443"),
+      at("https://user:pw@sid.example.com"),
+      `${CONTINUATION}#x`,
+      `${ISSUER}/i/${HANDLE}/oauth2/token?client_id=app&request_uri=${ref}`,
+      `${ISSUER}/i/NOTAHANDLE/oauth2/authorize?client_id=app&request_uri=${ref}`,
+      `${ISSUER}/i/${HANDLE}/oauth2/authorize?client_id=app&redirect_uri=https%3A%2F%2Fevil.example.com`,
+      `${CONTINUATION}&redirect_uri=https%3A%2F%2Fevil.example.com`,
+      `${ISSUER}/i/${HANDLE}/oauth2/authorize?client_id=app&request_uri=https%3A%2F%2Fevil`,
+      `${ISSUER}/i/${HANDLE}/oauth2/authorize?client_id=&request_uri=${ref}`,
+    ]) {
+      expect(authorizationContinuation(rd, ISSUER), String(rd)).toBeNull();
+    }
+    expect(authorizationContinuation(CONTINUATION, "not a url")).toBeNull();
+  });
+});
+
 describe("useLoginSuccess (BFF cookie mode)", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -97,6 +144,53 @@ describe("useLoginSuccess (BFF cookie mode)", () => {
     expect(auth.isAuthenticated).toBe(false);
   });
 
+  // A sign-in an authorization request sent the user to returns the browser
+  // to that request's continuation, and does not touch the app's session.
+  it("returns to the authorization request it was sent from", async () => {
+    const leaveTo = vi.fn();
+    const { result, router } = await withApp(
+      () => useLoginSuccess("/account", { issuerOrigin: ISSUER, leaveTo }),
+      `/login?rd=${encodeURIComponent(CONTINUATION)}`,
+    );
+
+    await result.onLoginSuccess();
+
+    expect(leaveTo).toHaveBeenCalledWith(CONTINUATION);
+    expect(mockCheckBffSession).not.toHaveBeenCalled();
+    expect(router.currentRoute.value.path).toBe("/login");
+  });
+
+  // An `rd` that is not exactly a continuation at this installation's issuer
+  // is ignored: the user lands in the app, never at the given address.
+  it("ignores an rd it did not validate", async () => {
+    mockCheckBffSession.mockResolvedValue(null);
+    const leaveTo = vi.fn();
+    const { result, router } = await withApp(
+      () => useLoginSuccess("/account", { issuerOrigin: ISSUER, leaveTo }),
+      `/login?rd=${encodeURIComponent("https://evil.example.com/")}`,
+    );
+
+    await result.onLoginSuccess();
+
+    expect(leaveTo).not.toHaveBeenCalled();
+    expect(router.currentRoute.value.path).toBe("/account");
+  });
+
+  // Without an issuer origin no rd is followed at all.
+  it("follows no rd without an issuer origin", async () => {
+    mockCheckBffSession.mockResolvedValue(null);
+    const leaveTo = vi.fn();
+    const { result, router } = await withApp(
+      () => useLoginSuccess("/account", { leaveTo }),
+      `/login?rd=${encodeURIComponent(CONTINUATION)}`,
+    );
+
+    await result.onLoginSuccess();
+
+    expect(leaveTo).not.toHaveBeenCalled();
+    expect(router.currentRoute.value.path).toBe("/account");
+  });
+
   it("navigates when BFF session returns null (cookie not yet set)", async () => {
     mockCheckBffSession.mockResolvedValue(null);