@yielded/auth 0.1.0-beta.1

package/src/password/methods/verification.ts

@@ -0,0 +1,266 @@
+import { Cause, Crypto, DateTime, Effect, Encoding, Redacted, Schema } from "effect";
+
+import { hasCommitScope, type PreparedCommit } from "../../hooks/commit";
+import { HookDenied } from "../../hooks/models";
+import { LoginIdentifier } from "../../identity/models";
+import { reportAuthFailure } from "../../internal/diagnostics";
+import type { Email, SubjectId } from "../../Schema";
+import { TokenDigest } from "../../Schema";
+import { AuthenticationAuthority } from "../../sessions/AuthenticationAuthority";
+import {
+  SessionCapabilityUnsupported,
+  SessionInvalid,
+  SessionConflict,
+  PendingAuthenticationInvalid,
+  StaleAuthentication,
+} from "../../sessions/errors";
+import { type AuthenticationFlowId, type AuthenticationEvidence } from "../../sessions/models";
+import { PasswordHashingUnavailable, PasswordKdfBusy } from "../errors";
+import { PasswordHashing } from "../PasswordHashing";
+import { PasswordMethodUnsupported, PasswordRejected, PasswordUnavailable } from "./errors";
+import type { PasswordCredentialSnapshot } from "./models";
+import { PasswordPersistence } from "./PasswordPersistence";
+import type { PasswordMethodPolicy } from "./policy";
+import { snapshotPasswordCredential, snapshotPasswordRevision } from "./snapshot";
+
+export const passwordNoAmbient = Effect.fn("Passwords.noAmbient")(function* () {
+  if (yield* hasCommitScope) return yield* PasswordMethodUnsupported.make({});
+});
+
+export const readPasswordCommit = <A>(receipt: PreparedCommit<A>) =>
+  receipt.read.pipe(Effect.mapError(() => PasswordUnavailable.make({})));
+
+/** A commit acknowledgment can be lost after the session is durable. Only
+ * definite policy/credential rejection may become PasswordRejected. */
+export const passwordCompletionFailure = (
+  error: unknown,
+): PasswordRejected | PasswordUnavailable | PasswordMethodUnsupported | HookDenied => {
+  if (Schema.is(HookDenied)(error)) return error;
+  if (Schema.is(SessionCapabilityUnsupported)(error)) return PasswordMethodUnsupported.make({});
+  if (
+    Schema.is(
+      Schema.Union([
+        SessionCapabilityUnsupported,
+        SessionInvalid,
+        SessionConflict,
+        PendingAuthenticationInvalid,
+        StaleAuthentication,
+      ]),
+    )(error)
+  )
+    return PasswordRejected.make({});
+
+  return PasswordUnavailable.make({});
+};
+
+const noAmbient = passwordNoAmbient,
+  read = readPasswordCommit;
+
+export const passwordUnexpected = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(Effect.mapError(() => PasswordUnavailable.make({})));
+
+const unexpected = passwordUnexpected;
+
+const hashingInfrastructureFailure = Schema.is(
+  Schema.Union([PasswordHashingUnavailable, PasswordKdfBusy]),
+);
+
+/** Report infrastructure recovery without recording passwords or verifier data. */
+export const passwordHashingDiagnostics = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(
+    Effect.tapCause((cause) =>
+      reportAuthFailure(
+        "password-hashing",
+        Cause.fromReasons(
+          cause.reasons.filter(
+            (reason) => Cause.isFailReason(reason) && hashingInfrastructureFailure(reason.error),
+          ),
+        ),
+      ),
+    ),
+  );
+
+/** Verification owns attempt admission, settlement and the original proof instant. */
+export const makePasswordVerification = ({
+  moduleId,
+  policy,
+}: {
+  readonly moduleId: string;
+  readonly policy: PasswordMethodPolicy;
+}) => {
+  const encoder = new TextEncoder();
+  const tuple = Schema.fromJsonString(Schema.Array(Schema.String));
+
+  const digest = Effect.fn("Passwords.digest")(function* (parts: ReadonlyArray<string>) {
+    const crypto = yield* Crypto.Crypto;
+
+    const bytes = yield* unexpected(
+      crypto.digest("SHA-256", encoder.encode(Schema.encodeSync(tuple)(parts))),
+    );
+
+    return TokenDigest.make(Encoding.encodeBase64Url(bytes));
+  });
+
+  const identifier = (email: Email) => LoginIdentifier.make({ namespace: "email", value: email });
+
+  const sameCredential = (
+    credential: PasswordCredentialSnapshot,
+    revision: AuthenticationEvidence["revision"],
+  ) =>
+    credential.moduleId === moduleId &&
+    credential.revision.subjectId === revision.subjectId &&
+    credential.revision.securityRevision === revision.securityRevision &&
+    revision.credentials.some(
+      (item) =>
+        item.credentialId === credential.credentialId &&
+        item.revision === credential.credentialRevision,
+    );
+
+  const checkedPassword = Effect.fn("Passwords.checkedPassword")(
+    function* (password: Redacted.Redacted<string>, credential: PasswordCredentialSnapshot) {
+      const raw = Redacted.value(password);
+
+      yield* Schema.decodeEffect(Schema.String.check(Schema.isMaxLength(65536)))(raw);
+      if (credential.normalization === "none") return password;
+      yield* Schema.decodeEffect(Schema.String.check(Schema.isPattern(/^[^\uD800-\uDFFF]*$/u)))(
+        raw,
+      );
+
+      return Redacted.make(raw.normalize("NFC"));
+    },
+    Effect.mapError(() => PasswordRejected.make({})),
+  );
+
+  const verifyPassword = Effect.fn("Passwords.verifyPassword")(function* (
+    request: {
+      readonly flowId: AuthenticationFlowId;
+      readonly email: Email;
+      readonly password: Redacted.Redacted<string>;
+    },
+    action: "sign-in" | "change",
+    subjectId?: SubjectId,
+  ) {
+    yield* noAmbient();
+    const store = yield* PasswordPersistence;
+    const hasher = yield* PasswordHashing;
+    const authority = yield* AuthenticationAuthority;
+
+    const admitted = yield* read(
+      yield* store.admitAttempt(
+        {
+          moduleId,
+          action,
+          identifier: identifier(request.email),
+          subjectId,
+          policy: policy.attempts,
+        },
+        (decision, journal) => journal.prepare(decision),
+      ),
+    );
+
+    // All denied branches do one bounded dummy attempt too. Local admission can
+    // reject it; no claim of exact network timing is made.
+    if (admitted._tag === "Denied") {
+      yield* hasher.dummy(request.password).pipe(passwordHashingDiagnostics, Effect.ignore);
+
+      return yield* PasswordRejected.make({});
+    }
+
+    const candidate =
+      admitted.credential === undefined
+        ? undefined
+        : yield* snapshotPasswordCredential(admitted.credential);
+
+    const checked = yield* Effect.gen(function* () {
+      if (candidate === undefined) {
+        yield* hasher.dummy(request.password).pipe(passwordHashingDiagnostics);
+
+        return yield* PasswordRejected.make({});
+      }
+
+      const original = snapshotPasswordRevision(
+        yield* authority.capture(candidate.revision.subjectId, [candidate.credentialId]),
+      );
+
+      if (
+        !sameCredential(candidate, original) ||
+        (subjectId !== undefined && candidate.revision.subjectId !== subjectId) ||
+        candidate.identifier.value !== request.email
+      ) {
+        yield* hasher.dummy(request.password).pipe(passwordHashingDiagnostics);
+
+        return yield* PasswordRejected.make({});
+      }
+      const password = yield* checkedPassword(request.password, candidate);
+
+      const verified = yield* hasher.verify(password, candidate.verifier).pipe(
+        passwordHashingDiagnostics,
+        Effect.catchTag("PasswordVerifierInvalid", () =>
+          hasher
+            .dummy(password)
+            .pipe(
+              passwordHashingDiagnostics,
+              Effect.andThen(Effect.fail(PasswordRejected.make({}))),
+            ),
+        ),
+      );
+
+      if (!verified.matches) return yield* PasswordRejected.make({});
+      const verifiedAt = yield* DateTime.now;
+
+      const rehash =
+        action === "sign-in" && verified.needsRehash
+          ? {
+              expectedVersion: candidate.verifierVersion,
+              expectedVerifier: candidate.verifier,
+              nextVerifier: yield* hasher.hash(password).pipe(passwordHashingDiagnostics),
+            }
+          : undefined;
+
+      const evidence: AuthenticationEvidence = {
+        revision: original,
+        flowId: request.flowId,
+        bindingDigest: yield* digest([
+          "effect-auth/password-login/v1",
+          moduleId,
+          request.flowId,
+          request.email,
+        ]),
+        proofs: [
+          {
+            method: "password",
+            credentialId: candidate.credentialId,
+            factors: ["knowledge"],
+            userVerified: false,
+            phishingResistant: false,
+            verifiedAt,
+          },
+        ],
+      };
+
+      return { credential: candidate, evidence, rehash };
+    }).pipe(Effect.result);
+
+    const decision = yield* read(
+      yield* store.settleAttempt(
+        {
+          moduleId,
+          attemptId: admitted.attemptId,
+          captured: candidate,
+          outcome: checked._tag === "Success" ? "verified" : "rejected",
+          ...(checked._tag === "Success" && checked.success.rehash !== undefined
+            ? { rehash: checked.success.rehash }
+            : {}),
+        },
+        (value, journal) => journal.prepare(value),
+      ),
+    );
+
+    if (decision !== "verified" || checked._tag !== "Success")
+      return yield* PasswordRejected.make({});
+
+    return checked.success;
+  });
+
+  return { digest, identifier, verifyPassword };
+};

package/src/password/models.ts

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+
+/** Sensitive credential material; service boundaries wrap this in Redacted. */
+export const EncodedPasswordHash = Schema.String.check(Schema.isMaxLength(512)).pipe(
+  Schema.brand("effect-auth/EncodedPasswordHash"),
+);
+
+export type EncodedPasswordHash = typeof EncodedPasswordHash.Type;
+
+export const PasswordVerification = Schema.Struct({
+  matches: Schema.Boolean,
+  needsRehash: Schema.Boolean,
+});
+
+export type PasswordVerification = typeof PasswordVerification.Type;

package/src/password/policy.ts

@@ -0,0 +1,41 @@
+import { Effect, Schema } from "effect";
+
+import { PasswordConfigurationError } from "./errors";
+
+export const PasswordNormalization = Schema.Literals(["none", "NFC"]);
+export type PasswordNormalization = typeof PasswordNormalization.Type;
+
+export const PasswordPolicy = Schema.Struct({
+  /** Trusted method configuration; never accept this selection from a caller.
+   * always-mfa requires EVERY use, including recovery, to require another factor.
+   */
+  assurance: Schema.Literals(["single-factor", "always-mfa"]),
+  normalization: PasswordNormalization,
+  maximumCodePoints: Schema.Int.check(Schema.isBetween({ minimum: 64, maximum: 16384 })),
+  maximumBytes: Schema.Int.check(Schema.isBetween({ minimum: 256, maximum: 65536 })),
+});
+
+export type PasswordPolicy = typeof PasswordPolicy.Type;
+
+/** NIST SP800-63B-4: 15 code points, or 8 only when always part of MFA;
+ * support managers/paste/spaces, no composition rules or forced reset cadence.
+ */
+export const defaultPasswordPolicy: PasswordPolicy = Object.freeze({
+  assurance: "single-factor",
+  normalization: "NFC",
+  maximumCodePoints: 1024,
+  maximumBytes: 4096,
+});
+
+export const validatePasswordPolicy = Effect.fn("validatePasswordPolicy")(function* (
+  input: PasswordPolicy,
+) {
+  const policy = yield* Schema.decodeEffect(PasswordPolicy)(input).pipe(
+    Effect.mapError(() => PasswordConfigurationError.make({ component: "policy" })),
+  );
+
+  if (policy.maximumBytes < policy.maximumCodePoints * 4)
+    return yield* PasswordConfigurationError.make({ component: "policy" });
+
+  return Object.freeze(policy);
+});

package/src/phone/PhoneActionEvidence.ts

@@ -0,0 +1,26 @@
+import { Context, type Effect, type Redacted } from "effect";
+
+import type { AuthInvocation } from "../operations/context";
+import type { AuthenticationEvidence, AuthenticationRequirement } from "../sessions/models";
+import type { PhoneActionChallenge, PhoneActionRequired } from "./lifecycleModels";
+import type { PhoneOtpUnavailable } from "./models";
+
+/** Independent fresh authentication for phone custody mutation. A new phone code
+ * cannot authorize replacement of an existing account identifier or stronger factor.
+ * Consume one-use proofs before returning; later CAS failure does not refund them. */
+export class PhoneActionEvidence extends Context.Service<
+  PhoneActionEvidence,
+  {
+    readonly verify: (input: {
+      readonly invocation: AuthInvocation;
+      readonly challenge: PhoneActionChallenge;
+      readonly proof?: Redacted.Redacted<string>;
+    }) => Effect.Effect<
+      {
+        readonly evidence: AuthenticationEvidence;
+        readonly requirement: AuthenticationRequirement;
+      },
+      PhoneActionRequired | PhoneOtpUnavailable
+    >;
+  }
+>()("effect-auth/PhoneActionEvidence") {}

package/src/phone/PhoneAdmission.ts

@@ -0,0 +1,29 @@
+import { Context, type Effect } from "effect";
+
+import type { PhoneOtpUnavailable } from "./models";
+
+/** Distributed reservation, including suppressed recipients and failed/ambiguous sends.
+ * Identical request fingerprints may reuse admission, never a new message budget.
+ * Core ProofPersistence separately owns identifier/subject/resend/guess limits. */
+export class PhoneAdmission extends Context.Service<
+  PhoneAdmission,
+  {
+    readonly admit: (input: {
+      readonly moduleId: string;
+      readonly action: "request" | "attempt";
+      readonly requestId: string;
+      readonly fingerprint: string;
+      readonly networkKey: string;
+      /** At most the shared proof request retention; zero disables replay admission. */
+      readonly replayLifetimeMillis: number;
+    }) => Effect.Effect<boolean, PhoneOtpUnavailable>;
+    readonly cleanup: (input: {
+      readonly moduleId: string;
+      readonly limit: number;
+      readonly after?: string;
+    }) => Effect.Effect<
+      { readonly deleted: number; readonly nextCursor: string | null },
+      PhoneOtpUnavailable
+    >;
+  }
+>()("effect-auth/PhoneAdmission") {}

package/src/phone/PhoneDeliveryEligibility.ts

@@ -0,0 +1,9 @@
+import { Context, type Effect } from "effect";
+
+import type { PhoneNumber, PhoneOtpUnavailable } from "./models";
+
+/** Consumer controls supported numbering ranges, sender/template eligibility and vendor rules. */
+export class PhoneDeliveryEligibility extends Context.Service<
+  PhoneDeliveryEligibility,
+  { readonly allowed: (phoneNumber: PhoneNumber) => Effect.Effect<boolean, PhoneOtpUnavailable> }
+>()("effect-auth/PhoneDeliveryEligibility") {}

package/src/phone/PhonePersistence.ts

@@ -0,0 +1,43 @@
+import { Context, type Effect } from "effect";
+
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+import type { ProofCompletionPlan } from "../proofs/completion";
+import type { SubjectId } from "../Schema";
+import type {
+  PhoneActionAuthorization,
+  PhoneLifecycleAction,
+  PhoneLifecyclePolicy,
+  PhoneLifecycleTarget,
+  PhoneMutationDecision,
+} from "./lifecycleModels";
+import type { PhoneNumber, PhoneOtpUnavailable } from "./models";
+
+export interface PhoneMutation {
+  readonly moduleId: string;
+  readonly action: PhoneLifecycleAction;
+  readonly commandId: string;
+  readonly target: PhoneLifecycleTarget;
+  readonly authorization?: PhoneActionAuthorization;
+  readonly completion: ProofCompletionPlan;
+  readonly policy: PhoneLifecyclePolicy;
+}
+
+/** Custody tombstones are permanent. Recycled numbers never create, transfer or
+ * merge accounts automatically. Verification/change and continuation consumption
+ * share one native owner; a failed protected write cannot consume the proof. */
+export class PhonePersistence extends Context.Service<
+  PhonePersistence,
+  {
+    readonly target: (input: {
+      readonly moduleId: string;
+      readonly action: PhoneLifecycleAction;
+      readonly phoneNumber: PhoneNumber;
+      readonly subjectId?: SubjectId;
+      readonly sourcePhoneNumber?: PhoneNumber;
+    }) => Effect.Effect<PhoneLifecycleTarget, PhoneOtpUnavailable>;
+    readonly mutate: <A>(
+      input: PhoneMutation,
+      prepare: (decision: PhoneMutationDecision, journal: CommitJournal) => PreparedCommit<A>,
+    ) => Effect.Effect<PreparedCommit<A>, PhoneOtpUnavailable>;
+  }
+>()("effect-auth/PhonePersistence") {}

package/src/phone/PhoneRequestContext.ts

@@ -0,0 +1,7 @@
+import { Context, type Redacted } from "effect";
+
+/** Host-verified opaque network identity. Supply per invocation; never accept this in RPC payloads. */
+export class PhoneRequestContext extends Context.Service<
+  PhoneRequestContext,
+  { readonly networkKey: Redacted.Redacted<string> }
+>()("effect-auth/PhoneRequestContext") {}

package/src/phone/PhoneSignInTargets.ts

@@ -0,0 +1,19 @@
+import { Context, type Effect, type Option } from "effect";
+
+import type { PhoneCredentialSnapshot, PhoneNumber, PhoneOtpUnavailable } from "./models";
+
+/** Resolve only an existing active account with this exact verified phone credential.
+ * Reassignment/revocation must bump its authentication revision atomically. Custody
+ * revisions are never reused, including after deletion; outstanding codes cannot
+ * transfer to another account. Unknown or ineligible numbers return None.
+ * This capability never provisions or links an account based on a phone match.
+ */
+export class PhoneSignInTargets extends Context.Service<
+  PhoneSignInTargets,
+  {
+    readonly lookup: (input: {
+      readonly moduleId: string;
+      readonly phoneNumber: PhoneNumber;
+    }) => Effect.Effect<Option.Option<PhoneCredentialSnapshot>, PhoneOtpUnavailable>;
+  }
+>()("effect-auth/PhoneSignInTargets") {}

package/src/phone/definition.ts

@@ -0,0 +1,87 @@
+import type {
+  BindingOf,
+  ClaimsCodec,
+  StrategyBinding,
+  StrategyDefinition,
+  StrategyTypeLambda,
+} from "../auth/definition";
+import { makePhoneOtp, snapshotPhoneConfiguration } from "./module";
+
+export type PhoneOtpOptions<Namespace extends string | undefined = undefined> = Omit<
+  Parameters<typeof makePhoneOtp>[1],
+  "sessions"
+> & { readonly namespace?: Namespace };
+
+/** Bind the phone method to its Auth definition; runtime authorities come from Layers. */
+const captureDefine = <const Namespace extends string | undefined>(
+  _namespace: Namespace,
+  input: PhoneOtpOptions<Namespace>,
+) => {
+  const options = snapshotPhoneConfiguration(input);
+
+  return { options };
+};
+
+const bindDefine = <
+  const Namespace extends string | undefined,
+  Claims extends ClaimsCodec,
+  const Id extends string,
+  const SessionId extends string,
+>(
+  binding: StrategyBinding<Claims, Id, SessionId>,
+  captured: ReturnType<typeof captureDefine<Namespace>>,
+) => {
+  const { options } = captured;
+
+  return makePhoneOtp<Id, SessionId, Claims>(binding.namespace, {
+    ...options,
+    sessions: binding.sessions,
+  });
+};
+
+export interface DefineStrategy<Namespace extends string | undefined> extends StrategyTypeLambda {
+  readonly type: ReturnType<
+    typeof bindDefine<
+      Namespace,
+      BindingOf<this>["claims"],
+      BindingOf<this>["namespace"],
+      BindingOf<this>["sessionNamespace"]
+    >
+  >;
+}
+
+const define = <const Namespace extends string | undefined>(
+  namespace: Namespace,
+  input: PhoneOtpOptions<Namespace>,
+) => {
+  const captured = captureDefine<Namespace>(namespace, input);
+
+  const bind = <
+    Claims extends ClaimsCodec,
+    const Id extends string,
+    const SessionId extends string,
+  >(
+    binding: StrategyBinding<Claims, Id, SessionId>,
+  ) => bindDefine<Namespace, Claims, Id, SessionId>(binding, captured);
+
+  const definition: StrategyDefinition<DefineStrategy<Namespace>, Namespace> = {
+    namespace,
+    bind,
+  };
+
+  return Object.freeze(definition);
+};
+
+export function make<const Namespace extends string>(
+  options: PhoneOtpOptions<Namespace> & { readonly namespace: Namespace },
+): ReturnType<typeof define<Namespace>>;
+
+export function make<const Namespace extends string | undefined = undefined>(
+  options: PhoneOtpOptions<Namespace>,
+): ReturnType<typeof define<Namespace | undefined>>;
+
+export function make<const Namespace extends string | undefined>(
+  options: PhoneOtpOptions<Namespace>,
+) {
+  return define(options.namespace, options);
+}

package/src/phone/failure.ts

@@ -0,0 +1,40 @@
+import { Schema } from "effect";
+
+import { HookDenied } from "../hooks/models";
+import { RequestBindingInvalid } from "../operations/requestBinding";
+import { ProofInvalid, ProofRequestConflict } from "../proofs/errors";
+import {
+  PendingAuthenticationInvalid,
+  SessionConflict,
+  SessionInvalid,
+  StaleAuthentication,
+} from "../sessions/errors";
+import { PhoneActionRequired } from "./lifecycleModels";
+import { PhoneOtpRejected, PhoneOtpUnavailable } from "./models";
+
+/** An unavailable/ambiguous commit cannot truthfully be reported as rejected. */
+export const phoneFailure = (
+  error: unknown,
+): PhoneOtpRejected | PhoneOtpUnavailable | HookDenied => {
+  if (Schema.is(HookDenied)(error)) return error;
+  if (Schema.is(PhoneOtpUnavailable)(error)) return error;
+  if (
+    Schema.is(PhoneOtpRejected)(error) ||
+    Schema.is(RequestBindingInvalid)(error) ||
+    Schema.is(ProofInvalid)(error) ||
+    Schema.is(ProofRequestConflict)(error) ||
+    Schema.is(StaleAuthentication)(error) ||
+    Schema.is(PendingAuthenticationInvalid)(error) ||
+    Schema.is(SessionInvalid)(error) ||
+    Schema.is(SessionConflict)(error)
+  )
+    return PhoneOtpRejected.make({});
+
+  return PhoneOtpUnavailable.make({});
+};
+
+export const phoneActionFailure = (error: unknown) => {
+  const failure = phoneFailure(error);
+
+  return failure._tag === "PhoneOtpRejected" ? PhoneActionRequired.make({}) : failure;
+};