@effected/oidc 0.0.0-stage → 0.1.0

package/IdTokenClaims.js

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+import { RegisteredClaims } from "@effected/jwt";
+
+// src/IdTokenClaims.ts
+/**
+* The claims of an OpenID Connect ID token: RFC 7519's registered claims
+* plus the ID-token claims OpenID Connect Core 1.0 §2 adds.
+*
+* @remarks
+* Every claim is optional, so the schema decodes any provider's token, and
+* the schema is open: claims it does not name survive the decode. A
+* provider's own claims belong in a caller-supplied schema passed to
+* {@link (Oidc:class).verify} or {@link (Oidc:class).decodeUnverified},
+* not in a subclass here. `@effected/github`'s `ActionsOidcClaims` is one.
+*
+* Optional here does not mean optional in a verified token:
+* {@link (Oidc:class).verify} still requires `exp` and checks `iss`, `aud`,
+* `nbf` and `iat` whatever schema the payload is then decoded with.
+*
+* @public
+*/
+const IdTokenClaims = Schema.StructWithRest(Schema.Struct({
+	...RegisteredClaims.schema.fields,
+	/** Authorized party: the client the token was issued to, when it differs from the audience. */
+	azp: Schema.optionalKey(Schema.String),
+	/** The value the client sent in its authentication request, echoed back to bind the token to it. */
+	nonce: Schema.optionalKey(Schema.String),
+	/** When the end user authenticated, in seconds since the epoch. */
+	auth_time: Schema.optionalKey(Schema.Finite),
+	/** Authentication context class reference. */
+	acr: Schema.optionalKey(Schema.String),
+	/** Authentication method references, e.g. `pwd` or `mfa`. */
+	amr: Schema.optionalKey(Schema.Array(Schema.String))
+}), [Schema.Record(Schema.String, Schema.Unknown)]);
+
+export { IdTokenClaims };

package/IdentityToken.js

@@ -0,0 +1,74 @@
+import { Context, Effect, Layer, Redacted, Schema } from "effect";
+
+// src/IdentityToken.ts
+/**
+* Raised when an identity token cannot be obtained.
+*
+* @remarks
+* The audience is on the error because "which audience" is the first thing a
+* caller checks when an exchange is refused — a token minted for the wrong one
+* fails at the certificate authority, far from here.
+*
+* @public
+*/
+var IdentityTokenError = class extends Schema.TaggedError()("IdentityTokenError", {
+	/** The audience the token was requested for. */
+	audience: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Could not obtain an identity token for the "${this.audience}" audience`;
+	}
+};
+/** The token every double answers with unless a test says otherwise. */
+const TEST_TOKEN = "test-identity-token";
+/**
+* A source of workload identity tokens (OIDC): the input `@effected/sbom`'s
+* `SigstoreSigner` needs to obtain a signing certificate, and any other
+* consumer needs to present a workload identity.
+*
+* @remarks
+* In GitHub Actions, provide `ActionsIdentityToken.layer` from
+* `@effected/github-actions`. A consumer that already holds a token uses
+* {@link (IdentityToken:class).layerStatic}; tests use
+* {@link (IdentityToken:class).layerTest}.
+*
+* @example
+* ```ts
+* import { IdentityToken } from "@effected/oidc";
+* import { SigstoreSigner } from "@effected/sbom";
+* import { Layer } from "effect";
+*
+* const token = process.env.OIDC_TOKEN ?? "";
+* const layer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(token)));
+* ```
+*
+* @public
+*/
+var IdentityToken = class IdentityToken extends Context.Service()("@effected/oidc/IdentityToken") {
+	/**
+	* A layer answering with a token the caller already holds.
+	*
+	* @remarks
+	* For a consumer that obtained a token by some other route — a CI system
+	* that is not GitHub Actions, or a script that exchanged one itself. The
+	* audience is **ignored**, so it is the caller's job to have minted the token
+	* for the audience it will be used with; a layer cannot check that, and
+	* pretending otherwise would be theatre.
+	*/
+	static layerStatic = (token) => Layer.succeed(IdentityToken, { token: () => Effect.succeed(typeof token === "string" ? Redacted.make(token) : token) });
+	/**
+	* An in-memory double.
+	*
+	* @remarks
+	* Unlike `@effected/sbom`'s `SigstoreSigner.makeTest`, this one **answers** rather than
+	* dying: a fabricated OIDC token is a real answer to "give me a token" in a
+	* test, where a fabricated signature would be a lie about cryptography.
+	*/
+	static makeTest = (overrides = {}) => ({ token: overrides.token ?? (() => Effect.succeed(Redacted.make(TEST_TOKEN))) });
+	/** {@link (IdentityToken:class).makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(IdentityToken, IdentityToken.makeTest(overrides));
+};
+
+export { IdentityToken, IdentityTokenError };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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/Oidc.js

@@ -0,0 +1,94 @@
+import { Effect, Schema } from "effect";
+import { JwksResolver, Jws, Jwt, JwtError } from "@effected/jwt";
+
+// src/Oidc.ts
+const audiences = (audience) => typeof audience === "string" ? [audience] : audience;
+const decodeUnverified = Effect.fn("Oidc.decodeUnverified")(function* (token, claims) {
+	const { payload } = yield* Effect.fromResult(Jws.decodeUnverified(token));
+	return yield* Schema.decodeUnknownEffect(claims)(payload).pipe(Effect.mapError((cause) => new JwtError({
+		reason: "claims",
+		detail: "the payload does not match the expected claims",
+		cause
+	})));
+});
+const verify = Effect.fn("Oidc.verify")(function* (token, options) {
+	const expected = audiences(options.audience);
+	yield* Effect.annotateCurrentSpan({
+		issuer: options.issuer,
+		audience: expected.join(" ")
+	});
+	if (expected.length === 0 || expected.some((value) => value.length === 0)) return yield* new JwtError({
+		reason: "wrongAudience",
+		detail: "no audience was given; an OIDC token is never verified without one"
+	});
+	return yield* Jwt.verify(token, {
+		key: JwksResolver.forIssuer(options.issuer),
+		claims: options.claims,
+		issuer: options.issuer,
+		audience: expected,
+		...options.clockTolerance !== void 0 ? { clockTolerance: options.clockTolerance } : {}
+	});
+});
+/**
+* Read and verify OpenID Connect ID tokens.
+*
+* @remarks
+* Both operations fail with `@effected/jwt`'s `JwtError` and add no error of
+* their own; route on its `reason`, never on its message.
+*
+* @example
+* ```ts
+* import { JwksResolver } from "@effected/jwt";
+* import { IdTokenClaims, Oidc } from "@effected/oidc";
+* import { Effect } from "effect";
+*
+* const program = Oidc.verify("eyJ...", {
+*   issuer: "https://accounts.example.com",
+*   audience: "my-client-id",
+*   claims: IdTokenClaims,
+* });
+*
+* // JwksResolver.layer needs an HttpClient and a JwksStore, provided once at the edge.
+* export const main = program.pipe(Effect.provide(JwksResolver.layer));
+* ```
+*
+* @public
+*/
+var Oidc = class {
+	constructor() {}
+	/**
+	* Decode a token's payload with `claims` **without verifying it**.
+	*
+	* @remarks
+	* `Jws.decodeUnverified` plus a schema decode. No signature, issuer,
+	* audience or time check runs, as the name says. For reading a token this
+	* process was handed by a runtime it already trusts, never for
+	* authorizing anything: the result is whatever the token's author wrote.
+	*
+	* Fails as `malformed` when the token is not a compact JWS with a JOSE
+	* header, and as `claims` when the payload does not decode.
+	*
+	* @public
+	*/
+	static decodeUnverified = decodeUnverified;
+	/**
+	* Verify an ID token from `options.issuer` and decode its payload with
+	* `options.claims`.
+	*
+	* @remarks
+	* `Jwt.verify` keyed through `JwksResolver.forIssuer(options.issuer)`:
+	* the signature against the issuer's discovered JWKS, then `exp`, `nbf`,
+	* `iat`, `iss` and `aud`, then the schema decode. An empty audience, or an
+	* empty string among several, fails as `wrongAudience` before anything
+	* else, with no network call.
+	*
+	* The key is always looked up for the configured issuer, never for the
+	* token's own `iss`, so a token naming another issuer is never checked
+	* against that issuer's keys.
+	*
+	* @public
+	*/
+	static verify = verify;
+};
+
+export { Oidc };

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @effected/oidc
 
-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.
+OpenID Connect for Effect v4: the IdentityToken issuer contract, ID-token claims, and a discovery-backed verify over @effected/jwt.

package/index.d.ts

@@ -0,0 +1,214 @@
+import { Context, Duration, Effect, Layer, Redacted, Schema } from "effect";
+import { JwksResolver, JwtError } from "@effected/jwt";
+declare const IdentityTokenError_base: Schema.Class<IdentityTokenError, Schema.TaggedStruct<"IdentityTokenError", {
+  /** The audience the token was requested for. */
+  readonly audience: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when an identity token cannot be obtained.
+ *
+ * @remarks
+ * The audience is on the error because "which audience" is the first thing a
+ * caller checks when an exchange is refused — a token minted for the wrong one
+ * fails at the certificate authority, far from here.
+ *
+ * @public
+ */
+export declare class IdentityTokenError extends IdentityTokenError_base {
+  get message(): string;
+}
+/**
+ * The contract: one method, one audience, one redacted token.
+ *
+ * @remarks
+ * Deliberately smaller than any issuer's own surface. An implementation may
+ * cache, may decode claims, may do neither — none of that is the contract's
+ * business, and a wider contract would make github-actions' issuer the only
+ * thing that could satisfy it.
+ *
+ * @public
+ */
+interface IdentityTokenShape {
+  /** A workload identity token for `audience`. */
+  readonly token: (audience: string) => Effect.Effect<Redacted.Redacted<string>, IdentityTokenError>;
+}
+declare const IdentityToken_base: Context.ServiceClass<IdentityToken, "@effected/oidc/IdentityToken", IdentityTokenShape>;
+/**
+ * A source of workload identity tokens (OIDC): the input `@effected/sbom`'s
+ * `SigstoreSigner` needs to obtain a signing certificate, and any other
+ * consumer needs to present a workload identity.
+ *
+ * @remarks
+ * In GitHub Actions, provide `ActionsIdentityToken.layer` from
+ * `@effected/github-actions`. A consumer that already holds a token uses
+ * {@link (IdentityToken:class).layerStatic}; tests use
+ * {@link (IdentityToken:class).layerTest}.
+ *
+ * @example
+ * ```ts
+ * import { IdentityToken } from "@effected/oidc";
+ * import { SigstoreSigner } from "@effected/sbom";
+ * import { Layer } from "effect";
+ *
+ * const token = process.env.OIDC_TOKEN ?? "";
+ * const layer = SigstoreSigner.layer.pipe(Layer.provide(IdentityToken.layerStatic(token)));
+ * ```
+ *
+ * @public
+ */
+export declare class IdentityToken extends IdentityToken_base {
+  /**
+   * A layer answering with a token the caller already holds.
+   *
+   * @remarks
+   * For a consumer that obtained a token by some other route — a CI system
+   * that is not GitHub Actions, or a script that exchanged one itself. The
+   * audience is **ignored**, so it is the caller's job to have minted the token
+   * for the audience it will be used with; a layer cannot check that, and
+   * pretending otherwise would be theatre.
+   */
+  static readonly layerStatic: (token: Redacted.Redacted<string> | string) => Layer.Layer<IdentityToken>;
+  /**
+   * An in-memory double.
+   *
+   * @remarks
+   * Unlike `@effected/sbom`'s `SigstoreSigner.makeTest`, this one **answers** rather than
+   * dying: a fabricated OIDC token is a real answer to "give me a token" in a
+   * test, where a fabricated signature would be a lie about cryptography.
+   */
+  static readonly makeTest: (overrides?: Partial<IdentityTokenShape>) => IdentityTokenShape;
+  /** {@link (IdentityToken:class).makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<IdentityTokenShape>) => Layer.Layer<IdentityToken>;
+}
+/**
+ * The claims of an OpenID Connect ID token: RFC 7519's registered claims
+ * plus the ID-token claims OpenID Connect Core 1.0 §2 adds.
+ *
+ * @remarks
+ * Every claim is optional, so the schema decodes any provider's token, and
+ * the schema is open: claims it does not name survive the decode. A
+ * provider's own claims belong in a caller-supplied schema passed to
+ * {@link (Oidc:class).verify} or {@link (Oidc:class).decodeUnverified},
+ * not in a subclass here. `@effected/github`'s `ActionsOidcClaims` is one.
+ *
+ * Optional here does not mean optional in a verified token:
+ * {@link (Oidc:class).verify} still requires `exp` and checks `iss`, `aud`,
+ * `nbf` and `iat` whatever schema the payload is then decoded with.
+ *
+ * @public
+ */
+export declare const IdTokenClaims: Schema.StructWithRest<Schema.Struct<{
+  readonly iss: Schema.optionalKey<Schema.String>;
+  readonly sub: Schema.optionalKey<Schema.String>;
+  readonly aud: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>>;
+  readonly exp: Schema.optionalKey<Schema.Finite>;
+  readonly nbf: Schema.optionalKey<Schema.Finite>;
+  readonly iat: Schema.optionalKey<Schema.Finite>;
+  readonly jti: Schema.optionalKey<Schema.String>;
+  /** Authorized party: the client the token was issued to, when it differs from the audience. */
+  readonly azp: Schema.optionalKey<Schema.String>;
+  /** The value the client sent in its authentication request, echoed back to bind the token to it. */
+  readonly nonce: Schema.optionalKey<Schema.String>;
+  /** When the end user authenticated, in seconds since the epoch. */
+  readonly auth_time: Schema.optionalKey<Schema.Finite>;
+  /** Authentication context class reference. */
+  readonly acr: Schema.optionalKey<Schema.String>;
+  /** Authentication method references, e.g. `pwd` or `mfa`. */
+  readonly amr: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Unknown>]>;
+/**
+ * A decoded {@link (IdTokenClaims:variable)}.
+ *
+ * @public
+ */
+export type IdTokenClaims = typeof IdTokenClaims.Type;
+/**
+ * Options for {@link (Oidc:class).verify}.
+ *
+ * @typeParam S - The schema the verified payload is decoded with.
+ *
+ * @public
+ */
+interface OidcVerifyOptions<S extends Schema.Constraint> {
+  /**
+   * The issuer the token must come from. Its keys are discovered from
+   * `<issuer>/.well-known/openid-configuration` and `iss` must equal it.
+   */
+  readonly issuer: string;
+  /**
+   * The audience the token must have been minted for, or any of several.
+   * Required and non-empty: an OIDC issuer's one key set signs tokens for
+   * every relying party, so without an audience check a token minted for
+   * any of them would verify.
+   */
+  readonly audience: string | ReadonlyArray<string>;
+  /** The schema the payload is decoded with once every check has passed; `IdTokenClaims` for the standard set. */
+  readonly claims: S;
+  /** Allowed clock skew for `exp`, `nbf` and `iat`; 60 seconds by default. */
+  readonly clockTolerance?: Duration.Input | undefined;
+}
+/**
+ * Read and verify OpenID Connect ID tokens.
+ *
+ * @remarks
+ * Both operations fail with `@effected/jwt`'s `JwtError` and add no error of
+ * their own; route on its `reason`, never on its message.
+ *
+ * @example
+ * ```ts
+ * import { JwksResolver } from "@effected/jwt";
+ * import { IdTokenClaims, Oidc } from "@effected/oidc";
+ * import { Effect } from "effect";
+ *
+ * const program = Oidc.verify("eyJ...", {
+ *   issuer: "https://accounts.example.com",
+ *   audience: "my-client-id",
+ *   claims: IdTokenClaims,
+ * });
+ *
+ * // JwksResolver.layer needs an HttpClient and a JwksStore, provided once at the edge.
+ * export const main = program.pipe(Effect.provide(JwksResolver.layer));
+ * ```
+ *
+ * @public
+ */
+export declare class Oidc {
+  private constructor();
+  /**
+   * Decode a token's payload with `claims` **without verifying it**.
+   *
+   * @remarks
+   * `Jws.decodeUnverified` plus a schema decode. No signature, issuer,
+   * audience or time check runs, as the name says. For reading a token this
+   * process was handed by a runtime it already trusts, never for
+   * authorizing anything: the result is whatever the token's author wrote.
+   *
+   * Fails as `malformed` when the token is not a compact JWS with a JOSE
+   * header, and as `claims` when the payload does not decode.
+   *
+   * @public
+   */
+  static readonly decodeUnverified: <S extends Schema.Constraint>(token: string, claims: S) => Effect.Effect<S["Type"], JwtError, S["DecodingServices"]>;
+  /**
+   * Verify an ID token from `options.issuer` and decode its payload with
+   * `options.claims`.
+   *
+   * @remarks
+   * `Jwt.verify` keyed through `JwksResolver.forIssuer(options.issuer)`:
+   * the signature against the issuer's discovered JWKS, then `exp`, `nbf`,
+   * `iat`, `iss` and `aud`, then the schema decode. An empty audience, or an
+   * empty string among several, fails as `wrongAudience` before anything
+   * else, with no network call.
+   *
+   * The key is always looked up for the configured issuer, never for the
+   * token's own `iss`, so a token naming another issuer is never checked
+   * against that issuer's keys.
+   *
+   * @public
+   */
+  static readonly verify: <S extends Schema.Constraint>(token: string, options: OidcVerifyOptions<S>) => Effect.Effect<S["Type"], JwtError, JwksResolver | S["DecodingServices"]>;
+}
+export type { IdentityTokenShape, OidcVerifyOptions };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,5 @@
+import { IdentityToken, IdentityTokenError } from "./IdentityToken.js";
+import { IdTokenClaims } from "./IdTokenClaims.js";
+import { Oidc } from "./Oidc.js";
+
+export { IdTokenClaims, IdentityToken, IdentityTokenError, Oidc };

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "@effected/oidc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/oidc",
+	"version": "0.1.0",
+	"private": false,
+	"description": "OpenID Connect for Effect v4: the IdentityToken issuer contract, ID-token claims, and a discovery-backed verify over @effected/jwt.",
+	"keywords": [
+		"oidc",
+		"openid-connect",
+		"id-token",
+		"jwt",
+		"jwks",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/oidc#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/oidc"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effected/jwt": "^0.5.0"
+	},
+	"peerDependencies": {
+		"effect": "^4.0.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}