@house-rules/auth-jwt 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,64 @@
+# @house-rules/auth-jwt: notes for agents
+
+## What it does
+
+It fills the `Authenticator` slot from `@house-rules/application`. `verify(token, { audience? })` checks a JWT's signature against a JSON Web Key Set, its `iss`, a required `exp` and its `nbf`, a non-empty string `sub`, and its `aud` when an audience is set. A good token becomes a `Principal`: `issuer`, `subject`, `audience`, `scopes` and every claim. A bad one fails with `TokenRejected`, whose `reason` is `invalid`, `expired`, `wrong_audience`, `wrong_issuer` or `unavailable` (the key set could not be fetched). It uses `jose` 6.2.12. Identity also uses jose for its passwords issuer; auth-jwt remains the pure token checker. It owns no tables, no migrations and no identity: who the subject is in the app is another package's job. Version 0.1.0 is ready for its first npm release, not yet published. It peers on exact `@house-rules/application` 0.2.0, `@house-rules/domain` 0.2.0 and Effect 4.0.3.
+
+## How an app mounts it
+
+1. [ ] For identity providers, choose `Identity.passwords(...)` or `Identity.oidc(...)` in Identity's options. Identity builds the matching auth-jwt verifier once. Direct uses, such as a separate MCP resource verifier, still provide one layer in the composition root:
+
+   ```ts
+   AuthJwt.layer({ issuer: "https://auth.example.com", audience: "https://app.example/mcp" })
+   // or, for Clerk:
+   AuthJwt.clerk({ publishableKey, authorizedParties: ["https://app.example.com"] })
+   ```
+
+2. [ ] Handle `AuthJwtConfigInvalid`, an unavailable-kind acquisition error. The layer fails with it when the issuer is not an absolute http(s) URL, the JWKS URL (explicit, or derived from the issuer) is not https, `clockTolerance` is not a finite, non-negative number, the Clerk key is not a `pk_test_` or `pk_live_` key, or the Clerk `authorizedParties` list is empty or contains blank values.
+3. [ ] Fill a way's Who with `Identity.who({ token, audience?, challenge? })` from identity, or a custom `WhoSocket`. It reads the token with `tokenFrom`, verifies it, then resolves the Actor. Rejected tokens become 401 `Refused`; unavailable verification becomes 503. One token source: `tokenFrom(incoming, "bearer")` or `tokenFrom(incoming, { cookie: "__session" })`. Several places, tried in order, first token wins: `tokenFrom(incoming, ["bearer", { cookie: "__session" }])`. List the bearer header first, so a script's header beats a browser's cookie.
+4. [ ] In tests, sign tokens with `AuthJwtTesting.keys` and pass its `jwks` to the layer, so no test touches the network. `keys.sign(claims, header?)` accepts protected-header fields for locally signed kind fixtures.
+
+No `migrations.json` line.
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `issuer` | required | the exact `iss` every token carries |
+| `audience` | none | the `aud` a token must name; a `verify` call's `audience` wins over it |
+| `jwksUrl` | `<issuer>/.well-known/jwks.json` | where the public keys are fetched and cached; https only |
+| `jwks` | none | a fixed public key set used instead of `jwksUrl` |
+| `clockTolerance` | `0`, Clerk `5` | seconds of skew allowed on `exp` and `nbf` |
+| `authorizedParties` | none; required by Clerk | a present `azp` must be a string exactly matching a listed value; absent `azp` passes |
+| `rejectPending` | `false` | reject `sts = pending` when true |
+
+`AuthJwt.clerk({ publishableKey, authorizedParties, audience?, clockTolerance?, jwks?, rejectPending? })` derives the issuer from the key: the base64 after the prefix is the Frontend API host plus `$`, and the issuer is `https://<host>`. JWKS comes from `<issuer>/.well-known/jwks.json` unless `jwks` is supplied. The authorized-party list must contain at least one nonblank string. `AuthJwt.clerkIssuer(key)` returns that issuer as an `Option`.
+
+### Providers needing the protected header
+
+`AuthJwt.verifier(options)` is an `Effect<AuthJwtVerifier, AuthJwtConfigInvalid>`. Acquire it once. Its `verify(token, { audience? })` returns an Effect of `{ header, principal }`, failing with `TokenRejected`. The header is jose's verified `protectedHeader`, never unverified decoded input. `AuthJwt.layer` wraps this verifier and drops the header; its Principal-only contract is unchanged.
+
+`AuthJwt.clerkOptions(ClerkOptions)` is an Effect of `AuthJwtOptions`. It validates the publishable key, nonempty authorized-party list and clock tolerance, and derives issuer, JWKS URL and the 5-second default. Identity's Clerk provider must reuse this function instead of copying the defaults.
+
+Apply pure `AuthJwt.clerkKind(header, principal.claims)` only after verification. It returns `oauth_access` for `typ` exactly `at+jwt` or `application/at+jwt`, then `machine` for `sub` starting `mch_`. A session requires `typ` absent or exactly `JWT`, `sub` starting `user_`, a nonempty string `sid` and no `act` claim. Anything else is `unknown`, which the caller must refuse. The classifier neither accepts impersonation nor chooses what a way admits. Any explicit impersonation override belongs to identity.
+
+The Clerk rules follow the accepted identity proposal's C1, C3, C4, C10 and C28 facts. Before production use, verify a real session token's header and claims against the predicate. Local fixtures are not proof of a production instance's token shape.
+
+## Local issuer: dev and demos only
+
+`AuthJwtLocal` signs tokens in process so a demo can sign in with no identity provider. Never mount it in production: whoever can call `issue` can sign in as anyone.
+
+- `AuthJwtLocal.make({ issuer?, audience?, ttlSeconds? })` is an `Effect` of `{ issuer, audience?, jwks, issue, layer }`. It makes a fresh ES256 key pair in memory per call, so tokens die with the process and one issuer's tokens fail another's layer.
+- `issue({ sub, name?, ...claims })` is an `Effect<string>`. It sets `iss`, `iat`, `exp` (now plus `ttlSeconds`) and `aud` after the given claims, so a caller cannot extend a token. Time comes from `Clock`.
+- `layer` is a `Layer<Authenticator>` on the same verify code as `AuthJwt.layer`, with the local key set injected.
+- `AuthJwtLocal.layer(options)` provides both `Authenticator` and the `AuthJwtLocalIssuer` service, whose `issue` a test or demo sign-in binding can yield.
+- Defaults: issuer `https://dev-issuer.invalid`, no audience, `ttlSeconds` 3600. A bad issuer or a `ttlSeconds` that is not a positive whole number fails with `AuthJwtConfigInvalid`.
+- `make` and `layer` refuse outside development/test themselves with unavailable `AuthJwtConfigInvalid`, option `NODE_ENV`. Effect Config reads NODE_ENV; after trimming and lowercasing, only development or test passes. Missing and blank values refuse. A host NODE_ENV, when present, must pass too.
+- The public `requireDevelopmentSigning(refused)` helper implements this guard and raises the caller's typed `refused()` error. Identity reuses it for devLocal and ephemeral passwords signing.
+
+## Fixed rules
+
+- No token passes without a matching signature, issuer, non-empty string subject and unexpired time. A token with no `exp` is refused. There is no option to skip a check.
+- The audience is checked only when one is set. An MCP route sets it to its resource URL, so a token for another resource is refused.
+- `scope` (space-separated) wins over `scp` (an array or a string). Missing both gives no scopes. Scopes are parsed but do not narrow access yet. Token-scope narrowing is a later addition. Composition plugs `Party.may()` once to resolve the person's roles. Ways narrow access only through feature exposure; MCP exposes read features and uses the same roles as HTTP. `defineWay({ features })` exposes features, never module operations.
+- `verify` reads the time from Effect's `Clock`, so `TestClock` drives expiry in tests.
+- No email, no user lookup and no session issuing here.
+- Module user-facing errors keep their messages; unavailable and plumbing errors use fixed public text, with diagnostic details kept in separate fields or causes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Szwajka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @house-rules/auth-jwt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fills the `Authenticator` slot from `@house-rules/application` by verifying JWTs against a JSON Web Key Set, with a Clerk preset. Plain JWT works with any OpenID-style issuer that publishes its keys.
+
+```ts
+import { AuthJwt } from "@house-rules/auth-jwt";
+
+const authenticator = AuthJwt.layer({ issuer: "https://auth.example.com" });
+const clerk = AuthJwt.clerk({
+  publishableKey: "pk_live_...",
+  authorizedParties: ["https://app.example.com"],
+});
+```
+
+The layer fills the lower `Authenticator` slot, not a way's Who socket. Pair it with `Identity.who({ token, audience?, challenge? })` from identity, or a custom `WhoSocket` that resolves an Actor. Application never imports this plug. The way exposes features through `defineWay({ features })`; May owns feature access separately.
+
+`AuthJwtConfigInvalid` carries unavailable kind for acquisition failures. `verify(token, { audience? })` returns a `Principal` or fails with `TokenRejected`. Keys come from `<issuer>/.well-known/jwks.json` by default, or from `jwksUrl` (https only), or from a fixed `jwks` set. `AuthJwtTesting.keys` gives a local key pair and a signer for tests.
+
+## Verified headers and Clerk tokens
+
+`AuthJwt.verifier(options)` returns an Effect of a verifier. Its `verify(token, { audience? })` returns `{ header, principal }` only after signature and claim checks pass. `header` is jose's verified protected header. `AuthJwt.layer(options)` uses the same checks and returns only the Principal, as before.
+
+Generic JWT options accept an optional `authorizedParties` list. A present `azp` must be a string exactly matching a listed value; an absent `azp` passes. Without the list, generic verification keeps its existing behaviour. `rejectPending: true` rejects `sts = pending`.
+
+Breaking for the next release: the Clerk preset now requires a nonempty `authorizedParties` list (Clerk's `azp` check) and defaults `clockTolerance` to 5 seconds (was 0). Existing `AuthJwt.clerk({ publishableKey })` calls must add `authorizedParties`. Generic JWT verification still defaults to 0. `AuthJwt.clerkOptions(options)` returns an Effect of `AuthJwtOptions` with the issuer and JWKS URL derived from the publishable key. Use it with `AuthJwt.verifier` to keep those defaults in a provider that needs the verified header:
+
+```ts
+const options = yield* AuthJwt.clerkOptions({ publishableKey, authorizedParties });
+const verifier = yield* AuthJwt.verifier(options);
+const { header, principal } = yield* verifier.verify(token);
+const kind = AuthJwt.clerkKind(header, principal.claims);
+```
+
+`clerkKind` is pure and must receive verified data. In order, it returns:
+
+- `oauth_access` for protected-header `typ` equal to `at+jwt` or `application/at+jwt`.
+- `machine` for a subject starting with `mch_`.
+- `session` for `typ` absent or `JWT`, a subject starting with `user_`, a nonempty string `sid` and no `act` claim.
+- `unknown` otherwise.
+
+Classification does not admit a credential or resolve an Actor. The caller must refuse kinds it does not accept, including `unknown`. Impersonation policy belongs to identity, not this classifier. Before production use, check that a real Clerk session token satisfies this predicate; locally signed fixtures do not prove the instance's token shape.
+
+## Local issuer
+
+For dev and demos only, never production, `AuthJwtLocal` is a local issuer: an in-memory key pair whose tokens the normal verify path accepts.
+
+```ts
+import { AuthJwtLocal, AuthJwtLocalIssuer } from "@house-rules/auth-jwt";
+
+const local = yield* AuthJwtLocal.make({ audience: "http://localhost:3000/api", ttlSeconds: 3600 });
+const token = yield* local.issue({ sub: "ada", name: "Ada" }); // Effect<string>
+// local.layer: Layer<Authenticator>; local.jwks: the public key set
+
+// or one layer with both the Authenticator and the AuthJwtLocalIssuer service
+const dev = AuthJwtLocal.layer({ audience: "http://localhost:3000/api" });
+```
+
+Whoever can call `issue` can sign in as anyone. `AuthJwtLocal.make` and `.layer` refuse outside development/test themselves with unavailable `AuthJwtConfigInvalid`. They read NODE_ENV through Effect Config, trim and lowercase it, and accept only `development` or `test`. A host NODE_ENV, when present, must also pass. Missing and blank values refuse.
+
+The public `requireDevelopmentSigning(refused)` helper applies that same guard and returns the caller's typed error from `refused()`. Identity reuses it for devLocal and ephemeral passwords signing.
+
+`issue` drops the reserved claims `iss`, `aud`, `exp`, `iat`, `nbf` and `jti` from the claims you pass. The issuer sets `iss`, `iat` and `exp`, and sets `aud` only when you configured an audience; otherwise the token has no `aud`.
+
+Version 0.1.0 is prepared for its first public release, not yet live on npm. Pin `@house-rules/application` 0.2.0, `@house-rules/domain` 0.2.0 and Effect 4.0.3 exactly. It depends on `jose` 6.2.12. See `AGENTS.md` for options and fixed rules.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { AuthJwt, type AuthJwtVerifier, type VerifiedToken } from "./jwt/auth-jwt.ts";
+export type { ClerkKind } from "./jwt/clerk-kind.ts";
+export { requireDevelopmentSigning } from "./local-issuer/development-signing.ts";
+export { AuthJwtConfigInvalid } from "./jwt/config-invalid.ts";
+export type { AuthJwtOptions, ClerkOptions } from "./jwt/options.ts";
+export { AuthJwtTesting, type TestKeys } from "./test-keys/test-keys.ts";
+export { AuthJwtLocal, type AuthJwtLocalKit, type AuthJwtLocalOptions, } from "./local-issuer/auth-jwt-local.ts";
+export { AuthJwtLocalIssuer, type LocalClaims, type LocalIssuerService, } from "./local-issuer/local-issuer.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { AuthJwt } from "./jwt/auth-jwt.js";
+export { requireDevelopmentSigning } from "./local-issuer/development-signing.js";
+export { AuthJwtConfigInvalid } from "./jwt/config-invalid.js";
+export { AuthJwtTesting } from "./test-keys/test-keys.js";
+export { AuthJwtLocal, } from "./local-issuer/auth-jwt-local.js";
+export { AuthJwtLocalIssuer, } from "./local-issuer/local-issuer.js";

package/dist/jwt/auth-jwt.d.ts

@@ -0,0 +1,56 @@
+import { Authenticator, type Principal, TokenRejected } from "@house-rules/application";
+import { Effect, Layer } from "effect";
+import { type JWTHeaderParameters, type JWTVerifyGetKey } from "jose";
+import { clerkIssuer } from "./clerk-issuer.ts";
+import { clerkKind } from "./clerk-kind.ts";
+import { AuthJwtConfigInvalid } from "./config-invalid.ts";
+import type { AuthJwtOptions, ClerkOptions } from "./options.ts";
+export declare const issuerUrl: (value: string) => Effect.Effect<never, AuthJwtConfigInvalid, never> | Effect.Effect<URL, never, never>;
+export type VerifiedToken = Readonly<{
+    header: JWTHeaderParameters;
+    principal: Principal;
+}>;
+export type AuthJwtVerifier = Readonly<{
+    verify: (token: string, options?: Readonly<{
+        audience?: string;
+    }>) => Effect.Effect<VerifiedToken, TokenRejected>;
+}>;
+export declare const authenticator: (options: AuthJwtOptions, keys: JWTVerifyGetKey, clockTolerance: number) => Authenticator["Service"];
+declare const layer: (options: AuthJwtOptions) => Layer.Layer<Authenticator, AuthJwtConfigInvalid>;
+declare const clerk: (options: ClerkOptions) => Layer.Layer<Authenticator, AuthJwtConfigInvalid>;
+export declare const AuthJwt: {
+    readonly layer: typeof layer;
+    readonly verifier: (options: Readonly<{
+        issuer: string;
+        audience?: string;
+        jwksUrl?: string;
+        clockTolerance?: number;
+        jwks?: import("jose").JSONWebKeySet;
+        authorizedParties?: ReadonlyArray<string>;
+        rejectPending?: boolean;
+    }>) => Effect.Effect<Readonly<{
+        verify: (token: string, options?: Readonly<{
+            audience?: string;
+        }>) => Effect.Effect<VerifiedToken, TokenRejected>;
+    }>, AuthJwtConfigInvalid, never>;
+    readonly clerk: typeof clerk;
+    readonly clerkOptions: (options: Readonly<{
+        publishableKey: string;
+        authorizedParties: ReadonlyArray<string>;
+        rejectPending?: boolean;
+        audience?: string;
+        clockTolerance?: number;
+        jwks?: import("jose").JSONWebKeySet;
+    }>) => Effect.Effect<Readonly<{
+        issuer: string;
+        audience?: string;
+        jwksUrl?: string;
+        clockTolerance?: number;
+        jwks?: import("jose").JSONWebKeySet;
+        authorizedParties?: ReadonlyArray<string>;
+        rejectPending?: boolean;
+    }>, AuthJwtConfigInvalid, never>;
+    readonly clerkIssuer: typeof clerkIssuer;
+    readonly clerkKind: typeof clerkKind;
+};
+export {};

package/dist/jwt/auth-jwt.js

@@ -0,0 +1,101 @@
+import { Authenticator, TokenRejected } from "@house-rules/application";
+import { DateTime, Effect, Layer, Predicate } from "effect";
+import { createLocalJWKSet, createRemoteJWKSet, jwtVerify, } from "jose";
+import { clerkIssuer } from "./clerk-issuer.js";
+import { clerkKind } from "./clerk-kind.js";
+import { AuthJwtConfigInvalid } from "./config-invalid.js";
+import { principalOf } from "./principal-of.js";
+import { rejectionReason } from "./rejection.js";
+const absoluteUrl = (value, option, protocols) => {
+    const url = URL.canParse(value) ? new URL(value) : undefined;
+    return url !== undefined && protocols.includes(url.protocol)
+        ? Effect.succeed(url)
+        : Effect.fail(new AuthJwtConfigInvalid({
+            option,
+            message: `${option} must be an absolute ${protocols.includes("http:") ? "http(s)" : "https"} URL.`,
+        }));
+};
+export const issuerUrl = (value) => absoluteUrl(value, "issuer", ["https:", "http:"]);
+const jwksUrlOf = (value) => absoluteUrl(value, "jwksUrl", ["https:"]);
+const toleranceOf = (value) => value === undefined || (Number.isFinite(value) && value >= 0)
+    ? Effect.succeed(value ?? 0)
+    : Effect.fail(new AuthJwtConfigInvalid({
+        option: "clockTolerance",
+        message: "clockTolerance must be a finite, non-negative number of seconds.",
+    }));
+const keysOf = Effect.fnUntraced(function* (options) {
+    if (options.jwks !== undefined)
+        return createLocalJWKSet(options.jwks);
+    // Keys fetched over plain http could be swapped on the way, so the key set is https only.
+    const issuer = options.issuer.replace(/\/+$/u, "");
+    const url = yield* jwksUrlOf(options.jwksUrl ?? `${issuer}/.well-known/jwks.json`);
+    return createRemoteJWKSet(url);
+});
+const signedVerifier = (options, keys, clockTolerance) => ({
+    verify: (token, verifyOptions) => Effect.gen(function* () {
+        const now = yield* DateTime.now;
+        const audience = verifyOptions?.audience ?? options.audience;
+        const { payload, protectedHeader } = yield* Effect.tryPromise({
+            try: () => jwtVerify(token, keys, {
+                issuer: options.issuer,
+                requiredClaims: ["sub", "exp"],
+                currentDate: DateTime.toDate(now),
+                clockTolerance,
+                ...(audience === undefined ? {} : { audience }),
+            }),
+            catch: (error) => new TokenRejected({ reason: rejectionReason(error) }),
+        });
+        const azp = payload["azp"];
+        if (options.authorizedParties !== undefined &&
+            Object.hasOwn(payload, "azp") &&
+            (!Predicate.isString(azp) || !options.authorizedParties.includes(azp))) {
+            return yield* new TokenRejected({ reason: "invalid" });
+        }
+        if (options.rejectPending === true && payload["sts"] === "pending") {
+            return yield* new TokenRejected({ reason: "invalid" });
+        }
+        const principal = yield* Effect.fromOption(principalOf(payload)).pipe(Effect.mapError(() => new TokenRejected({ reason: "invalid" })));
+        return { header: protectedHeader, principal };
+    }),
+});
+export const authenticator = (options, keys, clockTolerance) => {
+    const checked = signedVerifier(options, keys, clockTolerance);
+    return {
+        verify: (token, verifyOptions) => Effect.map(checked.verify(token, verifyOptions), ({ principal }) => principal),
+    };
+};
+const verifier = Effect.fnUntraced(function* (options) {
+    yield* issuerUrl(options.issuer);
+    const clockTolerance = yield* toleranceOf(options.clockTolerance);
+    const keys = yield* keysOf(options);
+    return signedVerifier(options, keys, clockTolerance);
+});
+const layer = (options) => Layer.effect(Authenticator, Effect.map(verifier(options), (checked) => ({
+    verify: (token, verifyOptions) => Effect.map(checked.verify(token, verifyOptions), ({ principal }) => principal),
+})));
+const clerkOptions = Effect.fnUntraced(function* (options) {
+    const issuer = yield* Effect.fromOption(clerkIssuer(options.publishableKey)).pipe(Effect.mapError(() => new AuthJwtConfigInvalid({
+        option: "publishableKey",
+        message: "publishableKey is not a Clerk pk_test_ or pk_live_ key.",
+    })));
+    if (!Array.isArray(options.authorizedParties) ||
+        options.authorizedParties.length === 0 ||
+        !options.authorizedParties.every((party) => Predicate.isString(party) && party.trim() !== "")) {
+        return yield* new AuthJwtConfigInvalid({
+            option: "authorizedParties",
+            message: "authorizedParties must be a nonempty list of nonempty strings.",
+        });
+    }
+    const clockTolerance = yield* toleranceOf(options.clockTolerance ?? 5);
+    return {
+        issuer,
+        jwksUrl: `${issuer}/.well-known/jwks.json`,
+        clockTolerance,
+        authorizedParties: [...options.authorizedParties],
+        ...(options.audience === undefined ? {} : { audience: options.audience }),
+        ...(options.jwks === undefined ? {} : { jwks: options.jwks }),
+        ...(options.rejectPending === undefined ? {} : { rejectPending: options.rejectPending }),
+    };
+});
+const clerk = (options) => Layer.unwrap(Effect.map(clerkOptions(options), layer));
+export const AuthJwt = { layer, verifier, clerk, clerkOptions, clerkIssuer, clerkKind };

package/dist/jwt/clerk-issuer.d.ts

@@ -0,0 +1,2 @@
+import { Option } from "effect";
+export declare const clerkIssuer: (publishableKey: string) => Option.Option<string>;

package/dist/jwt/clerk-issuer.js

@@ -0,0 +1,13 @@
+import { Option, Result } from "effect";
+import { Base64 } from "effect/encoding";
+const keyPattern = /^pk_(?:test|live)_([A-Za-z0-9+/]+={0,2})$/u;
+const hostPattern = /^([a-z0-9.-]+\.[a-z]{2,})\$$/iu;
+const padded = (value) => value.padEnd(Math.ceil(value.length / 4) * 4, "=");
+export const clerkIssuer = (publishableKey) => {
+    const encoded = keyPattern.exec(publishableKey)?.[1];
+    if (encoded === undefined)
+        return Option.none();
+    const decoded = Result.getOrUndefined(Base64.decodeString(padded(encoded)));
+    const host = decoded === undefined ? undefined : hostPattern.exec(decoded)?.[1];
+    return host === undefined ? Option.none() : Option.some(`https://${host.toLowerCase()}`);
+};

package/dist/jwt/clerk-kind.d.ts

@@ -0,0 +1,2 @@
+export type ClerkKind = "session" | "oauth_access" | "machine" | "unknown";
+export declare const clerkKind: (header: Readonly<Record<string, unknown>>, claims: Readonly<Record<string, unknown>>) => ClerkKind;

package/dist/jwt/clerk-kind.js

@@ -0,0 +1,17 @@
+import { Predicate } from "effect";
+export const clerkKind = (header, claims) => {
+    if (header["typ"] === "at+jwt" || header["typ"] === "application/at+jwt") {
+        return "oauth_access";
+    }
+    const subject = claims["sub"];
+    if (Predicate.isString(subject) && subject.startsWith("mch_"))
+        return "machine";
+    return (header["typ"] === undefined || header["typ"] === "JWT") &&
+        Predicate.isString(subject) &&
+        subject.startsWith("user_") &&
+        Predicate.isString(claims["sid"]) &&
+        claims["sid"] !== "" &&
+        !Object.hasOwn(claims, "act")
+        ? "session"
+        : "unknown";
+};

package/dist/jwt/config-invalid.d.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+declare const AuthJwtConfigInvalid_base: Schema.Class<AuthJwtConfigInvalid, Schema.TaggedStruct<"AuthJwtConfigInvalid", {
+    readonly kind: Schema.tag<"unavailable">;
+    readonly option: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class AuthJwtConfigInvalid extends AuthJwtConfigInvalid_base {
+}
+export {};

package/dist/jwt/config-invalid.js

@@ -0,0 +1,8 @@
+import { errorKind } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+export class AuthJwtConfigInvalid extends Schema.TaggedError()("AuthJwtConfigInvalid", {
+    kind: errorKind("unavailable"),
+    option: Schema.String,
+    message: Schema.String,
+}) {
+}

package/dist/jwt/options.d.ts

@@ -0,0 +1,18 @@
+import type { JSONWebKeySet } from "jose";
+export type AuthJwtOptions = Readonly<{
+    issuer: string;
+    audience?: string;
+    jwksUrl?: string;
+    clockTolerance?: number;
+    jwks?: JSONWebKeySet;
+    authorizedParties?: ReadonlyArray<string>;
+    rejectPending?: boolean;
+}>;
+export type ClerkOptions = Readonly<{
+    publishableKey: string;
+    authorizedParties: ReadonlyArray<string>;
+    rejectPending?: boolean;
+    audience?: string;
+    clockTolerance?: number;
+    jwks?: JSONWebKeySet;
+}>;

package/dist/jwt/options.js

@@ -0,0 +1 @@
+export {};

package/dist/jwt/principal-of.d.ts

@@ -0,0 +1,4 @@
+import type { Principal } from "@house-rules/application";
+import { Option } from "effect";
+import type { JWTPayload } from "jose";
+export declare const principalOf: (payload: JWTPayload) => Option.Option<Principal>;

package/dist/jwt/principal-of.js

@@ -0,0 +1,19 @@
+import { Option, Predicate } from "effect";
+const strings = (value) => Array.isArray(value) ? value.filter(Predicate.isString) : [];
+const words = (value) => value.split(/\s+/u).filter((word) => word !== "");
+const scopesOf = (payload) => {
+    if (Predicate.isString(payload["scope"]))
+        return words(payload["scope"]);
+    const scp = payload["scp"];
+    return Predicate.isString(scp) ? words(scp) : strings(scp);
+};
+const audienceOf = (aud) => aud === undefined ? [] : Predicate.isString(aud) ? [aud] : strings(aud);
+export const principalOf = (payload) => Predicate.isString(payload.sub) && payload.sub !== ""
+    ? Option.some({
+        issuer: payload.iss ?? "",
+        subject: payload.sub,
+        audience: audienceOf(payload.aud),
+        scopes: scopesOf(payload),
+        claims: { ...payload },
+    })
+    : Option.none();

package/dist/jwt/rejection.d.ts

@@ -0,0 +1,2 @@
+import type { TokenRejectedReason } from "@house-rules/application";
+export declare const rejectionReason: (error: unknown) => TokenRejectedReason;

package/dist/jwt/rejection.js

@@ -0,0 +1,21 @@
+import { errors } from "jose";
+export const rejectionReason = (error) => {
+    if (error instanceof errors.JWTExpired)
+        return "expired";
+    if (error instanceof errors.JWTClaimValidationFailed) {
+        if (error.claim === "iss")
+            return "wrong_issuer";
+        if (error.claim === "aud")
+            return "wrong_audience";
+        return "invalid";
+    }
+    if (error instanceof errors.JWKSTimeout || error instanceof errors.JWKSInvalid) {
+        return "unavailable";
+    }
+    if (error instanceof errors.JOSEError) {
+        // jose fails a JWKS fetch with a non-200 status or a body that is not JSON as a generic error.
+        return error.code === "ERR_JOSE_GENERIC" ? "unavailable" : "invalid";
+    }
+    // Anything that is not a jose error comes from fetching the key set, such as a network failure.
+    return "unavailable";
+};

package/dist/local-issuer/auth-jwt-local.d.ts

@@ -0,0 +1,22 @@
+import { Authenticator } from "@house-rules/application";
+import { Effect, Layer } from "effect";
+import { AuthJwtConfigInvalid } from "../jwt/config-invalid.ts";
+import { AuthJwtLocalIssuer, type LocalIssuerService } from "./local-issuer.ts";
+export type AuthJwtLocalOptions = Readonly<{
+    issuer?: string;
+    audience?: string;
+    ttlSeconds?: number;
+}>;
+export type AuthJwtLocalKit = LocalIssuerService & Readonly<{
+    layer: Layer.Layer<Authenticator>;
+}>;
+declare const layer: (options?: AuthJwtLocalOptions) => Layer.Layer<Authenticator | AuthJwtLocalIssuer, AuthJwtConfigInvalid>;
+export declare const AuthJwtLocal: {
+    readonly make: (options?: Readonly<{
+        issuer?: string;
+        audience?: string;
+        ttlSeconds?: number;
+    }> | undefined) => Effect.Effect<AuthJwtLocalKit, AuthJwtConfigInvalid, never>;
+    readonly layer: typeof layer;
+};
+export {};

package/dist/local-issuer/auth-jwt-local.js

@@ -0,0 +1,52 @@
+import { Authenticator } from "@house-rules/application";
+import { Clock, Effect, Layer } from "effect";
+import { createLocalJWKSet, exportJWK, generateKeyPair, SignJWT } from "jose";
+import { authenticator, issuerUrl } from "../jwt/auth-jwt.js";
+import { AuthJwtConfigInvalid } from "../jwt/config-invalid.js";
+import { AuthJwtLocalIssuer } from "./local-issuer.js";
+import { requireDevelopmentSigning } from "./development-signing.js";
+const algorithm = "ES256";
+const kid = "house-rules-local";
+const reservedClaims = new Set(["iss", "aud", "exp", "iat", "nbf", "jti"]);
+const ttlOf = (value) => value === undefined || (Number.isInteger(value) && value > 0)
+    ? Effect.succeed(value ?? 3600)
+    : Effect.fail(new AuthJwtConfigInvalid({
+        option: "ttlSeconds",
+        message: "ttlSeconds must be a positive whole number of seconds.",
+    }));
+const make = Effect.fnUntraced(function* (options = {}) {
+    yield* requireDevelopmentSigning(() => new AuthJwtConfigInvalid({
+        option: "NODE_ENV",
+        message: "Development signing requires NODE_ENV development or test.",
+    }));
+    const issuer = options.issuer ?? "https://dev-issuer.invalid";
+    yield* issuerUrl(issuer);
+    const ttl = yield* ttlOf(options.ttlSeconds);
+    // A fresh key pair per issuer, kept in memory: its tokens die with the process.
+    const pair = yield* Effect.promise(() => generateKeyPair(algorithm));
+    const publicKey = yield* Effect.promise(() => exportJWK(pair.publicKey));
+    const jwks = { keys: [{ ...publicKey, kid, alg: algorithm, use: "sig" }] };
+    const verifier = authenticator({ issuer, jwks, ...(options.audience === undefined ? {} : { audience: options.audience }) }, createLocalJWKSet(jwks), 0);
+    const issue = (claims) => Effect.gen(function* () {
+        const now = Math.floor((yield* Clock.currentTimeMillis) / 1000);
+        // Reserved claims are the issuer's alone: a caller cannot mint a token that never expires or names another resource.
+        const payload = {
+            ...Object.fromEntries(Object.entries(claims).filter(([name]) => !reservedClaims.has(name))),
+            iss: issuer,
+            iat: now,
+            exp: now + ttl,
+            ...(options.audience === undefined ? {} : { aud: options.audience }),
+        };
+        return yield* Effect.promise(() => new SignJWT(payload).setProtectedHeader({ alg: algorithm, kid }).sign(pair.privateKey));
+    });
+    const kit = {
+        issuer,
+        jwks,
+        issue,
+        layer: Layer.succeed(Authenticator, verifier),
+        ...(options.audience === undefined ? {} : { audience: options.audience }),
+    };
+    return kit;
+});
+const layer = (options = {}) => Layer.unwrap(Effect.map(make(options), (kit) => Layer.merge(kit.layer, Layer.succeed(AuthJwtLocalIssuer, kit))));
+export const AuthJwtLocal = { make, layer };

package/dist/local-issuer/development-signing.d.ts

@@ -0,0 +1,2 @@
+import { Effect } from "effect";
+export declare const requireDevelopmentSigning: <E>(refused: () => E) => Effect.Effect<void, E>;

package/dist/local-issuer/development-signing.js

@@ -0,0 +1,10 @@
+import { Config, Effect } from "effect";
+const allowed = (value) => ["development", "test"].includes(value.trim().toLowerCase());
+export const requireDevelopmentSigning = (refused) => Effect.gen(function* () {
+    const environment = yield* Config.String("NODE_ENV").pipe(Config.withDefault(""), Effect.mapError(refused));
+    const host = globalThis.process?.env
+        ?.NODE_ENV;
+    // A custom ConfigProvider cannot conceal a non-development host.
+    if (!allowed(environment) || (host !== undefined && !allowed(host)))
+        return yield* Effect.fail(refused());
+});

package/dist/local-issuer/local-issuer.d.ts

@@ -0,0 +1,22 @@
+import { Context, type Effect } from "effect";
+import type { JSONWebKeySet } from "jose";
+export type LocalClaims = Readonly<{
+    sub: string;
+    name?: string;
+    [claim: string]: unknown;
+}>;
+export type LocalIssuerService = Readonly<{
+    issuer: string;
+    audience?: string;
+    jwks: JSONWebKeySet;
+    issue: (claims: LocalClaims) => Effect.Effect<string>;
+}>;
+declare const AuthJwtLocalIssuer_base: Context.ServiceClass<AuthJwtLocalIssuer, "@house-rules/auth-jwt/AuthJwtLocalIssuer", Readonly<{
+    issuer: string;
+    audience?: string;
+    jwks: JSONWebKeySet;
+    issue: (claims: LocalClaims) => Effect.Effect<string>;
+}>>;
+export declare class AuthJwtLocalIssuer extends AuthJwtLocalIssuer_base {
+}
+export {};

package/dist/local-issuer/local-issuer.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+export class AuthJwtLocalIssuer extends Context.Service()("@house-rules/auth-jwt/AuthJwtLocalIssuer") {
+}

package/dist/test-keys/test-keys.d.ts

@@ -0,0 +1,12 @@
+import { Effect } from "effect";
+import { type JSONWebKeySet, type JWTHeaderParameters } from "jose";
+export type TestKeys = Readonly<{
+    jwks: JSONWebKeySet;
+    sign: (payload: Readonly<Record<string, unknown>>, header?: Readonly<Partial<JWTHeaderParameters>>) => Effect.Effect<string>;
+}>;
+export declare const AuthJwtTesting: {
+    readonly keys: Effect.Effect<Readonly<{
+        jwks: JSONWebKeySet;
+        sign: (payload: Readonly<Record<string, unknown>>, header?: Readonly<Partial<JWTHeaderParameters>>) => Effect.Effect<string>;
+    }>, never, never>;
+};

package/dist/test-keys/test-keys.js

@@ -0,0 +1,19 @@
+import { Clock, Effect } from "effect";
+import { exportJWK, generateKeyPair, SignJWT, } from "jose";
+const algorithm = "ES256";
+const kid = "house-rules-test";
+const keys = Effect.gen(function* () {
+    const pair = yield* Effect.promise(() => generateKeyPair(algorithm, { extractable: true }));
+    const publicKey = yield* Effect.promise(() => exportJWK(pair.publicKey));
+    return {
+        jwks: { keys: [{ ...publicKey, kid, alg: algorithm, use: "sig" }] },
+        sign: (payload, header) => Effect.gen(function* () {
+            const now = Math.floor((yield* Clock.currentTimeMillis) / 1000);
+            const claims = { iat: now, exp: now + 600, ...payload };
+            return yield* Effect.promise(() => new SignJWT(claims)
+                .setProtectedHeader({ alg: algorithm, kid, ...header })
+                .sign(pair.privateKey));
+        }),
+    };
+});
+export const AuthJwtTesting = { keys };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@house-rules/auth-jwt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Fills the House Rules Authenticator slot by verifying JWTs against a JWKS, with a Clerk preset.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "effect": "4.0.3"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.3",
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "effect": "4.0.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakubSzwajka/house-rules.git",
+    "directory": "packages/auth-jwt"
+  },
+  "bugs": {
+    "url": "https://github.com/JakubSzwajka/house-rules/issues"
+  },
+  "homepage": "https://github.com/JakubSzwajka/house-rules",
+  "dependencies": {
+    "jose": "6.2.12"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "varlock run --path ../../ -- vitest run"
+  }
 }