@yielded/auth 0.1.0-beta.1

package/src/oauth/GithubOAuthProvider.ts

@@ -0,0 +1,106 @@
+import { Effect, Option, Redacted, Schema } from "effect";
+import { HttpClientRequest } from "effect/unstable/http";
+
+import { OAuthProviderError } from "./errors";
+import { type OAuthProvider, decodeStandardTokenGrant } from "./OAuthProvider";
+import { OAuthIdentity, OAuthProviderKey } from "./schema";
+
+export const githubOAuthProviderKey = Schema.decodeSync(OAuthProviderKey)("github");
+
+/**
+ * Credentials of the GitHub App whose user-to-server flow this provider
+ * drives. These are the app's *OAuth* credentials (client id and client
+ * secret) — not the private key or installation id used to mint
+ * app-as-bot installation tokens. The tokens this provider yields are GitHub
+ * App **user access tokens**: actions taken with them are attributed to the
+ * authorizing user, scoped by the app's permissions and the user's own access.
+ */
+export interface GithubOAuthOptions {
+  readonly clientId: string;
+  readonly clientSecret: Redacted.Redacted<string>;
+  /**
+   * Base URL of the GitHub web host owning `/login/oauth/*` (default
+   * `https://github.com`). Override for GitHub Enterprise Server or a test
+   * stand-in.
+   */
+  readonly webBaseUrl?: string;
+  /**
+   * Base URL of the GitHub REST API (default `https://api.github.com`).
+   * Override for GitHub Enterprise Server or a test stand-in.
+   */
+  readonly apiBaseUrl?: string;
+}
+
+const GithubUser = Schema.Struct({
+  id: Schema.Natural,
+  login: Schema.NonEmptyString,
+});
+
+// oxlint-disable-next-line no-restricted-properties -- The identity payload is untrusted JSON from GitHub.
+const decodeGithubUser = Schema.decodeUnknownEffect(GithubUser);
+
+const githubApiHeaders = {
+  accept: "application/vnd.github+json",
+  "user-agent": "effect-auth-oauth",
+  "x-github-api-version": "2022-11-28",
+};
+
+/**
+ * GitHub as an {@link OAuthProvider}. Everything here is mapping: endpoints,
+ * the standard token-response decoder (GitHub answers errors with status 200,
+ * which the standard decoder recognizes), identity normalization, and the
+ * revocation request shape.
+ *
+ * The identity preserves GitHub's stable numeric user id as
+ * `providerAccountId` (decimal string) and the login as `handle`. No scopes
+ * are requested: GitHub App user access tokens derive their permissions from
+ * the app installation, and GitHub ignores the OAuth-App-style `scope`
+ * parameter for them.
+ */
+export const makeGithubOAuthProvider = (options: GithubOAuthOptions): OAuthProvider => {
+  const webBaseUrl = options.webBaseUrl ?? "https://github.com";
+  const apiBaseUrl = options.apiBaseUrl ?? "https://api.github.com";
+
+  return {
+    key: githubOAuthProviderKey,
+    displayName: "GitHub",
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    endpoints: {
+      authorization: `${webBaseUrl}/login/oauth/authorize`,
+      token: `${webBaseUrl}/login/oauth/access_token`,
+    },
+    scopes: [],
+    authorizationParams: {},
+    decodeTokenGrant: decodeStandardTokenGrant(githubOAuthProviderKey),
+    identity: {
+      url: `${apiBaseUrl}/user`,
+      headers: githubApiHeaders,
+      decode: (payload) =>
+        decodeGithubUser(payload).pipe(
+          Effect.mapBoth({
+            onSuccess: (user) =>
+              OAuthIdentity.make({
+                provider: githubOAuthProviderKey,
+                providerAccountId: String(user.id),
+                handle: Option.some(user.login),
+              }),
+            onFailure: () =>
+              OAuthProviderError.make({
+                provider: githubOAuthProviderKey,
+                message: "GitHub returned an unrecognized user identity",
+              }),
+          }),
+        ),
+    },
+    revocation: Option.some((accessToken) =>
+      HttpClientRequest.delete(
+        `${apiBaseUrl}/applications/${encodeURIComponent(options.clientId)}/token`,
+      ).pipe(
+        HttpClientRequest.setHeaders(githubApiHeaders),
+        HttpClientRequest.basicAuth(options.clientId, options.clientSecret),
+        HttpClientRequest.bodyJsonUnsafe({ access_token: Redacted.value(accessToken) }),
+      ),
+    ),
+  };
+};

package/src/oauth/OAuth.ts

@@ -0,0 +1,436 @@
+import {
+  Context,
+  Crypto,
+  DateTime,
+  Duration,
+  Effect,
+  Encoding,
+  Layer,
+  Option,
+  Redacted,
+  Schema,
+} from "effect";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+
+import { AuthTokenCodec } from "../AuthTokenCodec";
+import { type AuthStoreError, AuthTokenError } from "../Errors";
+import type { SubjectId } from "../Schema";
+import {
+  type OAuthGrantRejected,
+  type UnknownOAuthProvider,
+  InvalidOAuthState,
+  OAuthAccessDenied,
+  OAuthConnectionNotFound,
+  OAuthProviderError,
+  OAuthReauthorizationRequired,
+} from "./errors";
+import { OAuthConnectionStore } from "./OAuthConnectionStore";
+import type { OAuthProvider, OAuthTokenGrant } from "./OAuthProvider";
+import { OAuthProviders } from "./OAuthProviders";
+import { OAuthStateStore } from "./OAuthStateStore";
+import { OAuthPolicy } from "./policy";
+import {
+  type OAuthProviderKey,
+  OAuthAuthorization,
+  OAuthCallbackParams,
+  OAuthConnection,
+  OAuthState,
+  OAuthTokens,
+} from "./schema";
+
+const stateTokenScope = "effect-auth/oauth-state-token";
+
+// oxlint-disable-next-line no-restricted-properties -- Callback query parameters are untrusted input.
+const decodeCallbackParams = Schema.decodeUnknownEffect(OAuthCallbackParams);
+
+export interface BeginOAuthInput {
+  readonly provider: OAuthProviderKey;
+  /** The application subject initiating the link; the state is bound to it. */
+  readonly subjectId: SubjectId;
+  /** The callback URL registered with the provider for this application. */
+  readonly redirectUri: string;
+}
+
+export interface CompleteOAuthInput {
+  readonly provider: OAuthProviderKey;
+  /** The subject of the *current* session; must match the one that began the flow. */
+  readonly subjectId: SubjectId;
+  /** Must equal the redirect URI the flow began with. */
+  readonly redirectUri: string;
+  /** The raw callback query parameters, validated internally. */
+  readonly params: unknown;
+}
+
+export type CompleteOAuthError =
+  | UnknownOAuthProvider
+  | InvalidOAuthState
+  | OAuthAccessDenied
+  | OAuthProviderError
+  | AuthStoreError
+  | AuthTokenError;
+
+/**
+ * Provider-independent OAuth 2.0 authorization-code workflow for linking
+ * provider accounts to application subjects. Providers contribute endpoints
+ * and response mappings through `OAuthProviders`; every security-relevant
+ * step — state issuance and single-use validation, subject and redirect-URI
+ * binding, code exchange, token refresh, revocation — lives here so it cannot
+ * vary per provider.
+ */
+export class OAuth extends Context.Service<
+  OAuth,
+  {
+    /**
+     * Issues a single-use, expiring `state` bound to the subject and redirect
+     * URI, and returns the provider authorization URL to redirect the actor
+     * to.
+     */
+    readonly begin: (
+      input: BeginOAuthInput,
+    ) => Effect.Effect<OAuthAuthorization, UnknownOAuthProvider | AuthStoreError | AuthTokenError>;
+    /**
+     * Validates the callback, consumes the state (single use, whatever the
+     * outcome), exchanges the code, fetches and validates the provider
+     * identity, and persists the connection — replacing any previous
+     * connection for the same subject and provider.
+     */
+    readonly complete: (
+      input: CompleteOAuthInput,
+    ) => Effect.Effect<OAuthConnection, CompleteOAuthError>;
+    /** The subject's current connection, if any. Token fields stay `Redacted`. */
+    readonly connection: (
+      provider: OAuthProviderKey,
+      subjectId: SubjectId,
+    ) => Effect.Effect<Option.Option<OAuthConnection>, AuthStoreError>;
+    /**
+     * A currently valid access token for the subject, refreshing (and
+     * persisting) it first when it is at or past the refresh margin. Fails
+     * with `OAuthReauthorizationRequired` when no live refresh path exists or
+     * the provider rejects the refresh grant.
+     */
+    readonly accessToken: (
+      provider: OAuthProviderKey,
+      subjectId: SubjectId,
+    ) => Effect.Effect<
+      Redacted.Redacted<string>,
+      | UnknownOAuthProvider
+      | OAuthConnectionNotFound
+      | OAuthReauthorizationRequired
+      | OAuthProviderError
+      | AuthStoreError
+    >;
+    /**
+     * Revokes the provider grant (when the provider supports revocation) and
+     * removes the stored connection. Idempotent: succeeds when no connection
+     * exists. A failed revocation keeps the connection so the caller can
+     * retry.
+     */
+    readonly disconnect: (
+      provider: OAuthProviderKey,
+      subjectId: SubjectId,
+    ) => Effect.Effect<void, UnknownOAuthProvider | OAuthProviderError | AuthStoreError>;
+  }
+>()("effect-auth/OAuth") {
+  static readonly layer: Layer.Layer<
+    OAuth,
+    never,
+    | OAuthProviders
+    | OAuthStateStore
+    | OAuthConnectionStore
+    | AuthTokenCodec
+    | Crypto.Crypto
+    | HttpClient.HttpClient
+  > = Layer.effect(OAuth)(
+    Effect.gen(function* () {
+      const policy = yield* OAuthPolicy;
+      const providers = yield* OAuthProviders;
+      const states = yield* OAuthStateStore;
+      const connections = yield* OAuthConnectionStore;
+      const codec = yield* AuthTokenCodec;
+      const crypto = yield* Crypto.Crypto;
+      const client = yield* HttpClient.HttpClient;
+
+      const randomStateToken = crypto.randomBytes(32).pipe(
+        Effect.map(Encoding.encodeBase64Url),
+        Effect.mapError(() => AuthTokenError.make({ message: "Secure randomness unavailable" })),
+      );
+
+      const unavailable = (provider: OAuthProviderKey, endpoint: string) =>
+        OAuthProviderError.make({
+          provider,
+          message: `The provider's ${endpoint} could not be reached`,
+        });
+
+      /**
+       * One token-endpoint call. Providers such as GitHub answer errors with
+       * status 200 and RFC-compliant providers answer them with status 400,
+       * so the payload — not the status — decides the outcome.
+       */
+      const requestTokenGrant = Effect.fn("OAuth.requestTokenGrant")(function* (
+        provider: OAuthProvider,
+        grantParams: Readonly<Record<string, string>>,
+      ): Effect.fn.Return<OAuthTokenGrant, OAuthGrantRejected | OAuthProviderError> {
+        const request = HttpClientRequest.post(provider.endpoints.token).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.bodyUrlParams({
+            ...grantParams,
+            client_id: provider.clientId,
+            client_secret: Redacted.value(provider.clientSecret),
+          }),
+        );
+
+        const response = yield* client
+          .execute(request)
+          .pipe(Effect.mapError(() => unavailable(provider.key, "token endpoint")));
+
+        const payload = yield* response.json.pipe(
+          Effect.mapError(() =>
+            OAuthProviderError.make({
+              provider: provider.key,
+              message: "The token endpoint returned a non-JSON response",
+            }),
+          ),
+        );
+
+        return yield* provider.decodeTokenGrant(payload);
+      });
+
+      const fetchIdentity = Effect.fn("OAuth.fetchIdentity")(function* (
+        provider: OAuthProvider,
+        accessToken: Redacted.Redacted<string>,
+      ) {
+        const request = HttpClientRequest.get(provider.identity.url).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.setHeaders(provider.identity.headers),
+          HttpClientRequest.bearerToken(accessToken),
+        );
+
+        const response = yield* client.execute(request).pipe(
+          Effect.flatMap(HttpClientResponse.filterStatusOk),
+          Effect.mapError(() => unavailable(provider.key, "identity endpoint")),
+        );
+
+        const payload = yield* response.json.pipe(
+          Effect.mapError(() =>
+            OAuthProviderError.make({
+              provider: provider.key,
+              message: "The identity endpoint returned a non-JSON response",
+            }),
+          ),
+        );
+
+        return yield* provider.identity.decode(payload);
+      });
+
+      const tokensFromGrant = (grant: OAuthTokenGrant, now: DateTime.Utc) =>
+        OAuthTokens.make({
+          accessToken: grant.accessToken,
+          tokenType: grant.tokenType,
+          accessTokenExpiresAt: Option.map(grant.expiresIn, (lifetime) =>
+            DateTime.addDuration(now, lifetime),
+          ),
+          refreshToken: grant.refreshToken,
+          refreshTokenExpiresAt: Option.map(grant.refreshTokenExpiresIn, (lifetime) =>
+            DateTime.addDuration(now, lifetime),
+          ),
+          scope: grant.scope,
+        });
+
+      return OAuth.of({
+        begin: Effect.fn("OAuth.begin")(function* (input) {
+          const provider = yield* providers.lookup(input.provider);
+          const stateToken = yield* randomStateToken;
+          const stateDigest = yield* codec.digestToken(Redacted.make(stateToken), stateTokenScope);
+          const now = yield* DateTime.now;
+          const expiresAt = DateTime.addDuration(now, policy.stateLifetime);
+
+          yield* states.issue(
+            OAuthState.make({
+              stateDigest,
+              provider: provider.key,
+              subjectId: input.subjectId,
+              redirectUri: input.redirectUri,
+              issuedAt: now,
+              expiresAt,
+            }),
+          );
+
+          // An unparseable authorization endpoint is a provider-configuration
+          // defect, not a request failure.
+          const url = yield* Effect.try(() => new URL(provider.endpoints.authorization)).pipe(
+            Effect.orDie,
+          );
+
+          url.searchParams.set("client_id", provider.clientId);
+          url.searchParams.set("redirect_uri", input.redirectUri);
+          url.searchParams.set("response_type", "code");
+          url.searchParams.set("state", stateToken);
+          if (provider.scopes.length > 0) {
+            url.searchParams.set("scope", provider.scopes.join(" "));
+          }
+          for (const [name, value] of Object.entries(provider.authorizationParams)) {
+            url.searchParams.set(name, value);
+          }
+
+          return OAuthAuthorization.make({ url: url.toString(), expiresAt });
+        }),
+
+        complete: Effect.fn("OAuth.complete")(function* (input) {
+          const provider = yield* providers.lookup(input.provider);
+
+          const params = yield* decodeCallbackParams(input.params).pipe(
+            Effect.mapError(() => InvalidOAuthState.make()),
+          );
+
+          if (params.state === undefined || params.state === "") {
+            return yield* InvalidOAuthState.make();
+          }
+
+          // The state is consumed before anything else is inspected, so every
+          // callback — including a denied or malformed one — burns it.
+          const stateDigest = yield* codec.digestToken(
+            Redacted.make(params.state),
+            stateTokenScope,
+          );
+
+          const state = yield* states.consume(stateDigest);
+
+          if (
+            state.provider !== provider.key ||
+            state.subjectId !== input.subjectId ||
+            state.redirectUri !== input.redirectUri
+          ) {
+            return yield* InvalidOAuthState.make();
+          }
+          if (params.error === "access_denied") {
+            return yield* OAuthAccessDenied.make();
+          }
+          if (params.error !== undefined) {
+            return yield* OAuthProviderError.make({
+              provider: provider.key,
+              message: "The provider rejected the authorization request",
+            });
+          }
+          if (params.code === undefined || params.code === "") {
+            return yield* InvalidOAuthState.make();
+          }
+
+          const grant = yield* requestTokenGrant(provider, {
+            grant_type: "authorization_code",
+            code: params.code,
+            redirect_uri: input.redirectUri,
+          }).pipe(
+            Effect.catchTag(
+              "OAuthGrantRejected",
+              (rejection): Effect.Effect<never, OAuthAccessDenied | OAuthProviderError> =>
+                rejection.code === "access_denied"
+                  ? OAuthAccessDenied.make()
+                  : OAuthProviderError.make({
+                      provider: provider.key,
+                      message: `The provider rejected the code exchange (${rejection.code})`,
+                    }),
+            ),
+          );
+
+          const identity = yield* fetchIdentity(provider, grant.accessToken);
+          const now = yield* DateTime.now;
+
+          const connection = OAuthConnection.make({
+            provider: provider.key,
+            subjectId: input.subjectId,
+            identity,
+            tokens: tokensFromGrant(grant, now),
+            connectedAt: now,
+            updatedAt: now,
+          });
+
+          yield* connections.put(connection);
+
+          return connection;
+        }),
+
+        connection: (provider, subjectId) => connections.get(provider, subjectId),
+
+        accessToken: Effect.fn("OAuth.accessToken")(function* (providerKey, subjectId) {
+          const existing = yield* connections.get(providerKey, subjectId);
+
+          if (Option.isNone(existing)) {
+            return yield* OAuthConnectionNotFound.make();
+          }
+          const current = existing.value;
+          const now = yield* DateTime.now;
+          const nowMillis = DateTime.toEpochMillis(now);
+          const marginMillis = Duration.toMillis(policy.accessTokenRefreshMargin);
+
+          const usable =
+            Option.isNone(current.tokens.accessTokenExpiresAt) ||
+            nowMillis + marginMillis <
+              DateTime.toEpochMillis(current.tokens.accessTokenExpiresAt.value);
+
+          if (usable) {
+            return current.tokens.accessToken;
+          }
+          const refreshToken = current.tokens.refreshToken;
+
+          const refreshTokenDead =
+            Option.isNone(refreshToken) ||
+            (Option.isSome(current.tokens.refreshTokenExpiresAt) &&
+              nowMillis >= DateTime.toEpochMillis(current.tokens.refreshTokenExpiresAt.value));
+
+          if (Option.isNone(refreshToken) || refreshTokenDead) {
+            return yield* OAuthReauthorizationRequired.make();
+          }
+          const provider = yield* providers.lookup(providerKey);
+
+          // A rejected refresh grant means the provider-side authorization is
+          // gone; only a fresh authorization can repair it.
+          const grant = yield* requestTokenGrant(provider, {
+            grant_type: "refresh_token",
+            refresh_token: Redacted.value(refreshToken.value),
+          }).pipe(Effect.catchTag("OAuthGrantRejected", () => OAuthReauthorizationRequired.make()));
+
+          const rotated = tokensFromGrant(grant, now);
+
+          // Providers that do not rotate refresh tokens omit them from the
+          // refresh response; the previous one then stays valid.
+          const tokens = Option.isSome(rotated.refreshToken)
+            ? rotated
+            : OAuthTokens.make({
+                ...rotated,
+                refreshToken: current.tokens.refreshToken,
+                refreshTokenExpiresAt: current.tokens.refreshTokenExpiresAt,
+              });
+
+          yield* connections.put(OAuthConnection.make({ ...current, tokens, updatedAt: now }));
+
+          return tokens.accessToken;
+        }),
+
+        disconnect: Effect.fn("OAuth.disconnect")(function* (providerKey, subjectId) {
+          const existing = yield* connections.get(providerKey, subjectId);
+
+          if (Option.isNone(existing)) {
+            return;
+          }
+          const provider = yield* providers.lookup(providerKey);
+
+          if (Option.isSome(provider.revocation)) {
+            const response = yield* client
+              .execute(provider.revocation.value(existing.value.tokens.accessToken))
+              .pipe(Effect.mapError(() => unavailable(provider.key, "revocation endpoint")));
+
+            const alreadyGone = response.status === 404 || response.status === 422;
+
+            if (!(response.status >= 200 && response.status < 300) && !alreadyGone) {
+              return yield* OAuthProviderError.make({
+                provider: provider.key,
+                message: "The provider refused the token revocation",
+              });
+            }
+          }
+          yield* connections.remove(providerKey, subjectId);
+        }),
+      });
+    }),
+  );
+}

package/src/oauth/OAuthAccountsPersistence.ts

@@ -0,0 +1,142 @@
+import { Context, type Effect } from "effect";
+
+import type { PreparedCommit } from "../hooks/commit";
+import type { SubjectId } from "../Schema";
+import type { SessionInvalidationWindow } from "../sessions/invalidation";
+import type {
+  OAuthAccountRevision,
+  OAuthActionAuthorization,
+  OAuthLinkAccess,
+  OAuthLinkClaim,
+  OAuthLinkClaimDecision,
+  OAuthLinkDecision,
+  OAuthLinkIssueDecision,
+  OAuthLinkOutcome,
+  OAuthLinkPendingFlow,
+  OAuthUnlinkDecision,
+  OAuthUnlinkInspection,
+} from "./accountsModels";
+import type { PrepareOAuthCommit } from "./OAuthSignInPersistence";
+import type { OAuthUnavailable } from "./signInErrors";
+import type {
+  OAuthCleanupInput,
+  OAuthCommandId,
+  OAuthCredentialSnapshot,
+  OAuthModuleId,
+} from "./signInModels";
+
+/** Same-owner semantic authority. Prepare is synchronous before physical commit;
+ * unknown outcomes discard receipts/events and never replay prepare. Standalone
+ * adapters reject ambient owners. No network, raw secrets, provider tokens, Claims
+ * or Registration data is accepted. Reads are nonconsuming and confer no CAS right.
+ */
+export class OAuthAccountsPersistence extends Context.Service<
+  OAuthAccountsPersistence,
+  {
+    /** Active original subject and authoritative credential revisions. Every policy,
+     * binding or credential-set change that affects authority advances securityRevision. */
+    readonly capture: (input: {
+      readonly moduleId: typeof OAuthModuleId.Type;
+      readonly subjectId: SubjectId;
+    }) => Effect.Effect<OAuthAccountRevision | undefined, OAuthUnavailable>;
+    /** Enforce unique module/flow and module/command, exact immutable context/sealed/
+     * retention data, active subject, original revisions, independent begin evidence,
+     * current enabled factor policy and authority-clock freshness in this same owner. */
+    readonly issue: <A>(
+      input: {
+        readonly flow: OAuthLinkPendingFlow;
+        readonly authorization: OAuthActionAuthorization;
+      },
+      prepare: PrepareOAuthCommit<typeof OAuthLinkIssueDecision.Type, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** Before action-factor consumption: check Pending, exact binder/flow/generation/
+     * provider/callback/response issuer, original active subject/revisions and expiry.
+     * Wrong credentials/subject never consume or terminalize the flow. */
+    readonly preflight: (
+      input: OAuthLinkAccess,
+    ) => Effect.Effect<OAuthLinkPendingFlow | undefined, OAuthUnavailable>;
+    /** Repeat every preflight predicate and exact inspected flow, then current fresh
+     * complete-action evidence/policy. Single CAS; authority sets fixed claim deadline
+     * = claimedAt + captured lifetime. Never reset Pending or renew the lease. */
+    readonly claim: <A>(
+      input: {
+        readonly access: OAuthLinkAccess;
+        readonly flow: OAuthLinkPendingFlow;
+        readonly claimId: OAuthLinkClaim["claimId"];
+        readonly authorization: OAuthActionAuthorization;
+      },
+      prepare: PrepareOAuthCommit<typeof OAuthLinkClaimDecision.Type, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** Exact claim CAS before deadline. Every outcome erases sealed material and
+     * terminalizes. Verified repeats active original subject/revisions, current action
+     * evidence/policy/freshness, and full provider+canonical issuer+stable subject
+     * uniqueness INCLUDING unresolved registration reservations. Never adopt by email.
+     * Same-subject connected-only ownership may add a login; another subject conflicts.
+     * Existing usable same-subject login may return unchanged. Changed joins credential,
+     * shared factor, revision advancement, pending/session/proof invalidation, terminal
+     * result and journal. No mutation/event for unchanged. No session is minted.
+     */
+    readonly settle: <A>(
+      input: {
+        readonly claim: OAuthLinkClaim;
+        readonly outcome: OAuthLinkOutcome;
+        readonly authorization: OAuthActionAuthorization;
+        readonly invalidation: SessionInvalidationWindow;
+        readonly nowMillis: number;
+      },
+      prepare: PrepareOAuthCommit<typeof OAuthLinkDecision.Type, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** Look up durable command first. Exact replay is authenticated safe metadata only
+     * for its original currently active subject under current metadata-access policy;
+     * no fresh factor is consumed. Compare module/command/subject/requested credential
+     * against durable original full intent. Cross-target/subject reuse conflicts.
+     * A missing credential/marker proves neither previous ownership nor rollback.
+     * New targets must be currently owned OAuth LOGIN credentials, not connected grants.
+     */
+    readonly inspectUnlink: (input: {
+      readonly moduleId: typeof OAuthModuleId.Type;
+      readonly subjectId: SubjectId;
+      readonly commandId: typeof OAuthCommandId.Type;
+      readonly credentialId: string;
+    }) => Effect.Effect<typeof OAuthUnlinkInspection.Type, OAuthUnavailable>;
+    /** Recheck exact original target/revisions and fresh independent action evidence,
+     * current enabled factor policy at authority time. Atomically evaluate POST-delete
+     * usable PRIMARY login paths using mapped method eligibility (active/verified/etc),
+     * not shared credential status alone. Factor-only TOTP, recovery, pending registration
+     * and connected grants do not count. Also retain ability to satisfy enabled factor
+     * policy; never silently disable MFA. Concurrent removals leave a viable method.
+     * Join login/shared-factor/proof removal, revision advancement, invalidation, immutable
+     * command result and journal. Retain full-tuple ownership while a connected reference
+     * exists, using an authoritative same-owner reference check when that capability is
+     * installed. No generic password store, async canUnlink boolean or read-count-delete.
+     * Exact durable replay returns original metadata with replayed=true; no writes,
+     * private commands/events/factor consumption. Command identity includes immutable
+     * original target tuple/revisions, not a new proof's bytes. Retain unresolved command
+     * outcomes; absent markers never justify automatic mutation retry.
+     */
+    readonly unlink: <A>(
+      input: {
+        readonly moduleId: typeof OAuthModuleId.Type;
+        readonly commandId: typeof OAuthCommandId.Type;
+        readonly credential: OAuthCredentialSnapshot;
+        readonly authorization: OAuthActionAuthorization;
+        readonly invalidation: SessionInvalidationWindow;
+        readonly nowMillis: number;
+        readonly retentionUntilMillis: number;
+      },
+      prepare: PrepareOAuthCommit<typeof OAuthUnlinkDecision.Type, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** Decode integer limit1..1000. Expire Pending->Rejected and Claimed->Ambiguous;
+     * erase sealed material, never reset. Conditional writes recheck authority clock and
+     * exact status. Terminal tombstones/commands retained through original retention and
+     * claim horizons; unresolved effects/reservations are never released by this cleanup.
+     */
+    readonly cleanup: <A>(
+      input: OAuthCleanupInput,
+      prepare: PrepareOAuthCommit<
+        { readonly terminalized: number; readonly removed: number; readonly hasMore: boolean },
+        A
+      >,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthAccountsPersistence") {}