@tdacorp/identity-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDACorp
+
+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

@@ -0,0 +1,299 @@
+# @tdacorp/identity-client
+
+OIDC relying-party client for TDACorp Identity: discovery, PKCE, token
+exchange/refresh/client-credentials, ID and access token verification, sealed
+cookie storage for OAuth transaction state, and Next.js App Router route
+handlers.
+
+Use this when a product wants to let a user sign in through TDACorp
+Identity's OIDC provider, or needs to verify a TDACorp-issued token
+server-side.
+
+## Install
+
+```bash
+npm install @tdacorp/identity-client
+```
+
+`@tdacorp/identity-authz` comes along as a real dependency, not a peer — no
+separate install needed unless you want to call its permission functions
+directly, outside of what this package already re-exposes on a verified
+access token's `roles` claim.
+
+## Quickstart
+
+The recommended shape: mount two Route Handlers with `./next`'s
+`createLoginRoute` and `createCallbackRoute`, request the full
+`openid profile email roles` scope, and verify access tokens later with
+`verifyAccessToken` plus `@tdacorp/identity-authz`'s `permits()`.
+
+```ts
+// app/api/auth/login/route.ts
+import { createLoginRoute } from '@tdacorp/identity-client/next'
+
+export const GET = createLoginRoute({
+  issuer: process.env.IDENTITY_ISSUER!,
+  clientId: process.env.IDENTITY_CLIENT_ID!,
+  redirectUri: `${process.env.APP_URL}/api/auth/callback`,
+  cookieSecret: process.env.COOKIE_SECRET!,
+  // scope defaults to "openid profile email roles" -- see the ./next section
+  // below for why omitting "roles" is a real functional loss, not a nicety.
+})
+```
+
+```ts
+// app/api/auth/callback/route.ts
+import { NextResponse } from 'next/server'
+import { createCallbackRoute } from '@tdacorp/identity-client/next'
+
+export const GET = createCallbackRoute({
+  issuer: process.env.IDENTITY_ISSUER!,
+  clientId: process.env.IDENTITY_CLIENT_ID!,
+  clientSecret: process.env.IDENTITY_CLIENT_SECRET!,
+  redirectUri: `${process.env.APP_URL}/api/auth/callback`,
+  cookieSecret: process.env.COOKIE_SECRET!,
+  onSuccess: async (tokens, idClaims, { returnTo }) => {
+    const response = NextResponse.redirect(new URL(returnTo ?? '/', process.env.APP_URL))
+    // Store tokens.accessToken / tokens.refreshToken in your own session --
+    // this package stops at verified claims, session storage is your call.
+    return response
+  },
+})
+```
+
+Both handlers seal the PKCE verifier and CSRF `state` into an encrypted
+cookie (via `./sealed`'s `seal()`/`unseal()`) rather than storing them in
+plaintext — you never handle that transaction cookie directly.
+
+Later, on a request that carries an access token, verify it and decide a
+permission with the same 3-branch switch `@tdacorp/identity-authz`'s own
+README documents:
+
+```ts
+import { verifyAccessToken } from '@tdacorp/identity-client'
+import { permits } from '@tdacorp/identity-authz'
+
+const result = await verifyAccessToken(accessToken, {
+  issuer: process.env.IDENTITY_ISSUER!,
+  audience: process.env.IDENTITY_CLIENT_ID!,
+})
+
+if (!result.success) {
+  // result.errors: TokenVerificationError[]
+} else if (result.data.kind === 'user') {
+  const permit = permits(result.data.roles, 'identity.users.view')
+
+  if (permit.decision === 'allow') {
+    // proceed
+  } else if (permit.decision === 'deny') {
+    // reject
+  } else {
+    switch (permit.reason) {
+      case 'ref':
+      case 'absent-claim':
+      case 'unknown-claim-version':
+      case 'malformed-claim':
+        // see @tdacorp/identity-authz's README for what each means
+        break
+    }
+  }
+}
+```
+
+Omitting `roles` from the requested scope means the minted token carries no
+`roles` claim at all, so every `permits()` check against it stays
+`indeterminate` with `reason: 'absent-claim'` forever — this is exactly why
+`createLoginRoute`'s default scope includes it.
+
+## Discovery
+
+```ts
+import { fetchDiscovery } from '@tdacorp/identity-client'
+
+const discovery = await fetchDiscovery('https://identity.tdacorp.in')
+// discovery.authorization_endpoint, discovery.token_endpoint, discovery.jwks_uri, ...
+```
+
+`fetchDiscovery` resolves an issuer's OpenID Provider Metadata document
+(`/.well-known/openid-configuration`), cached for 10 minutes with in-flight
+deduplication — concurrent callers for the same issuer during a cold start
+share one fetch rather than each firing their own. Before the result is
+trusted, it is validated: the document's `issuer` must match the URL you
+called with, and `jwks_uri` / `token_endpoint` must be https (loopback hosts
+excepted) and same-origin with the issuer. This is what stops a compromised
+edge cache or a cached error page from redirecting key material or the token
+endpoint somewhere untrusted.
+
+Most callers reach `fetchDiscovery` indirectly — every function below calls
+it internally.
+
+## PKCE
+
+```ts
+import { generateCodeVerifier, generateCodeChallenge, generateState } from '@tdacorp/identity-client'
+
+const codeVerifier = generateCodeVerifier()
+const codeChallenge = await generateCodeChallenge(codeVerifier)
+const state = generateState()
+```
+
+RFC 7636 code verifier, S256 code challenge, and CSRF `state` generation.
+Built on Web Crypto (`crypto.getRandomValues` / `crypto.subtle.digest`) only,
+never Node's `crypto` module, because a consuming app's auth routes may run
+on an Edge runtime rather than Node — Web Crypto is the one API both are
+guaranteed to have.
+
+## Token exchange, refresh, and client credentials
+
+Authorization code exchange (RFC 6749 §4.1.3 / RFC 7636 §4.5):
+
+```ts
+import { exchangeAuthorizationCode } from '@tdacorp/identity-client'
+
+const tokens = await exchangeAuthorizationCode({
+  issuer: 'https://identity.tdacorp.in',
+  clientId: process.env.IDENTITY_CLIENT_ID!,
+  clientSecret: process.env.IDENTITY_CLIENT_SECRET!, // omit for a public client using PKCE alone
+  code,
+  redirectUri,
+  codeVerifier,
+})
+```
+
+Refresh (RFC 6749 §6), returning a classified outcome instead of throwing —
+so a transient infrastructure failure is never mistaken for a rejected
+refresh token:
+
+```ts
+import { refreshTokens } from '@tdacorp/identity-client'
+
+const outcome = await refreshTokens({ issuer, clientId, clientSecret, refreshToken })
+
+if (outcome.outcome === 'success') {
+  // outcome.tokens
+} else if (outcome.outcome === 'terminal') {
+  // the refresh token is confirmed dead -- safe to clear it now
+} else {
+  // outcome.outcome === 'transient': status still unknown, retry later.
+  // Do NOT clear the refresh token or the session built on it.
+}
+```
+
+Machine-to-machine calls with no end user use `clientCredentialsGrant` (RFC
+6749 §4.4) instead, always with a confidential `clientSecret` since there is
+no PKCE verifier to authenticate a public client with. A token minted this
+way carries no `sub` and no `roles` claim — verifying it with
+`verifyAccessToken` returns the `kind: 'machine'` variant of
+`VerifiedAccessToken`, distinct from the `kind: 'user'` variant a normal
+login produces, so reading `.sub` or `.roles` off the wrong branch is a
+compile error rather than `undefined`.
+
+## Verification
+
+```ts
+import { verifyIdToken, verifyAccessToken } from '@tdacorp/identity-client'
+
+const result = await verifyAccessToken(accessToken, {
+  issuer: 'https://identity.tdacorp.in',
+  audience: clientId,
+  authorizedParties: [clientId],
+})
+```
+
+`verifyIdToken` and `verifyAccessToken` verify signature, issuer, audience,
+and expiry (60 seconds of clock-skew tolerance), returning
+`{ success: false, errors }` for any expected verification failure instead of
+throwing — only a missing `options.issuer` / `options.audience` throws, since
+that is a programming error rather than a property of the token. The
+signature algorithm is pinned to EdDSA; a token signed any other way is
+rejected outright.
+
+`authorizedParties` is worth setting deliberately. Every TDACorp product
+shares one platform domain and one identity server, so a token minted for
+one product is not otherwise prevented from being replayed against another
+product on the same platform — the plain `audience` check only confirms a
+token is valid for *some* resource server, not that it was issued through a
+client you trust. `authorizedParties` checks the token's `azp` claim (falling
+back to a single-string `aud`) against an allowlist you provide, closing that
+gap.
+
+## `./sealed`
+
+```ts
+import { seal, unseal } from '@tdacorp/identity-client/sealed'
+
+const sealedValue = await seal(
+  { state, codeVerifier },
+  { secret: process.env.COOKIE_SECRET!, ttlSeconds: 600, purpose: 'my-app:oauth-transaction' }
+)
+// store sealedValue as a cookie value
+
+const transaction = await unseal<{ state: string; codeVerifier: string }>(sealedValue, {
+  secret: process.env.COOKIE_SECRET!,
+  purpose: 'my-app:oauth-transaction',
+})
+// transaction is null on any failure (expired, tampered, wrong secret/purpose)
+```
+
+`seal()` encrypts a JWT-payload-shaped object into a compact JWE
+(`alg: "dir"`, `enc: "A256GCM"`) rather than merely signing it, so a cookie's
+contents are opaque to whoever holds it, not just tamper-evident. The
+content-encryption key is derived via HKDF from your secret, mixed with a
+`purpose` string, so the same base secret used for two different purposes
+(an OAuth transaction cookie and an unrelated signed claim, say) derives two
+different keys — sealing under one purpose and unsealing under another fails
+rather than silently succeeding on the wrong data. `seal()` throws
+synchronously if the result would exceed a 4096-byte hard limit, rather than
+truncating or chunking it across multiple cookies. `secret` also accepts a
+`Record<number, string>` rotation map: `seal()` always encrypts under the
+highest-numbered key and stamps it into the JWE header as `kid`, and
+`unseal()` reads `kid` back to pick the matching key, so values sealed under
+a retired key keep decrypting.
+
+## `./next`
+
+```ts
+import { createLoginRoute, createCallbackRoute } from '@tdacorp/identity-client/next'
+```
+
+`createLoginRoute` and `createCallbackRoute` build plain Next.js App Router
+Route Handlers (see the Quickstart above) — there is deliberately no
+middleware or route-matcher factory alongside them. Clerk deprecated its own
+middleware route-matcher helper in favor of protecting resources as close to
+them as possible, because middleware path-matching can silently diverge from
+how the framework actually routes a request. Auth0's Next.js SDK needed a
+breaking rename (`middleware.ts` → `proxy.ts`) to keep working on Next.js
+16's Node runtime — not a stable foundation to wrap a second time. This
+package ships Route Handlers a consuming app mounts wherever it wants
+instead.
+
+## Limitations in v0.1
+
+- **Only `client_secret_basic` client authentication is supported** for the
+  authorization-code exchange (`exchangeAuthorizationCode` sends an HTTP
+  Basic `Authorization` header when a `clientSecret` is given). A relying
+  party configured on TDACorp Identity for `client_secret_post` cannot use
+  `exchangeAuthorizationCode` as-is today — the token endpoint will reject
+  the request.
+- **No built-in fallback for an `indeterminate` `permits()` result.** That is
+  `@tdacorp/identity-authz`'s concern, not this package's, but worth knowing
+  up front since most integrations hit both together — see that package's
+  README for what each `indeterminate` reason means and why it is not
+  resolved to a default for you.
+
+## Documentation
+
+This package's TSDoc-annotated types are the API reference: viewable via
+editor hover, or in the shipped `.d.ts` files. There is no separate docs
+site.
+
+## Contributing
+
+This package is developed inside TDACorp's internal monorepo, which isn't
+public, so there's no GitHub issue tracker to file against. Bug reports go to
+security@tdacorp.in instead — the same address for a genuine bug as for a
+security report.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/chunk-KLXEPP4S.js

@@ -0,0 +1,80 @@
+// src/sealed.ts
+import {
+  EncryptJWT,
+  jwtDecrypt,
+  decodeProtectedHeader,
+  errors as joseErrors
+} from "jose";
+async function deriveContentEncryptionKey(secret, purpose) {
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits(
+    { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: encoder.encode(purpose) },
+    keyMaterial,
+    256
+  );
+  return new Uint8Array(bits);
+}
+function resolveSealingKey(secret) {
+  if (typeof secret === "string") return { secretValue: secret };
+  const keyNumbers = Object.keys(secret).map(Number);
+  if (keyNumbers.length === 0) throw new Error("seal: secret key-rotation map is empty");
+  const highest = Math.max(...keyNumbers);
+  return { kid: String(highest), secretValue: secret[highest] };
+}
+var MAX_SEALED_BYTES = 4096;
+async function seal(payload, options) {
+  const { kid, secretValue } = resolveSealingKey(options.secret);
+  const cek = await deriveContentEncryptionKey(secretValue, options.purpose);
+  const header = {
+    alg: "dir",
+    enc: "A256GCM",
+    ...kid !== void 0 ? { kid } : {}
+  };
+  const sealed = await new EncryptJWT(payload).setProtectedHeader(header).setIssuedAt().setExpirationTime(`${options.ttlSeconds}s`).encrypt(cek);
+  const byteLength = new TextEncoder().encode(sealed).length;
+  if (byteLength > MAX_SEALED_BYTES) {
+    throw new Error(
+      `seal: sealed payload is ${byteLength} bytes, over the ${MAX_SEALED_BYTES}-byte limit (MAX_SEALED_BYTES). Shrink the payload -- do not chunk it across cookies; see MAX_SEALED_BYTES's own docblock for why.`
+    );
+  }
+  return sealed;
+}
+function resolveUnsealingKey(secret, kid) {
+  if (typeof secret === "string") return { secretValue: secret };
+  if (kid === void 0 || !(Number(kid) in secret)) return { reason: "unknown-key" };
+  return { secretValue: secret[Number(kid)] };
+}
+function classifyUnsealError(error) {
+  const code = error instanceof joseErrors.JOSEError ? error.code : void 0;
+  return code === "ERR_JWT_EXPIRED" ? "expired" : "invalid";
+}
+async function unseal(sealedValue, options) {
+  let kid;
+  try {
+    kid = decodeProtectedHeader(sealedValue).kid;
+  } catch {
+    options.onError?.("invalid");
+    return null;
+  }
+  const resolved = resolveUnsealingKey(options.secret, kid);
+  if ("reason" in resolved) {
+    options.onError?.(resolved.reason);
+    return null;
+  }
+  try {
+    const cek = await deriveContentEncryptionKey(resolved.secretValue, options.purpose);
+    const { payload } = await jwtDecrypt(sealedValue, cek);
+    return payload;
+  } catch (error) {
+    const reason = classifyUnsealError(error);
+    options.onError?.(reason);
+    return null;
+  }
+}
+
+export {
+  MAX_SEALED_BYTES,
+  seal,
+  unseal
+};