@vouchington/utils 0.8.0 → 0.9.0

package/README.md

@@ -85,14 +85,20 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 - `oidc-id-token`: Node-only (`node:crypto`) RS256 ID-token verifier with an injected `fetch`, JWKS
   URI, issuers, and audiences. It caches the JWKS with a TTL, refreshes once on a `kid` miss, checks
   `iat` skew and an optional (hashed) nonce, and throws `OidcVerificationError` with a `code`.
-  `googleProfileFromClaims` and `appleProfileFromClaims` map claims to a profile; account policy
+  `googleProfileFromClaims`, `appleProfileFromClaims`, and `microsoftProfileFromClaims` map claims to a profile; account policy
   and HTTP error mapping stay in the application.
 - `oauth-providers`: authorization-code redemption for GitHub, X, LinkedIn, Microsoft, Google, and Facebook. Each
   provider's `redeem(input, { fetch, signal, now })` returns `{ tokens, profile }`; `verifiedEmail`
-  follows each provider's own rule. Microsoft Graph `mail` is not proof of ownership, so it is
-  only reported as verified with `trustMailAsVerified: true`. Credentials, tenant, and the egress-guarded `fetch` are
-  injected; failures throw `OAuthProviderError` (`provider`, `kind`, `status`). Persistence and
-  HTTP error mapping stay in the application.
+  follows each provider's own rule. Microsoft verifies an ID token with the tenant JWKS and uses only an `email` claim with boolean
+  `xms_edov: true` for `verifiedEmail`; Graph `mail` stays in profile data without verification. The
+  authorization URL must request `microsoftAuthorizationScopes` (`openid email User.Read`) so Graph
+  `/me` is authorized.
+  Facebook keeps Graph email as unverified data and supports native tokens through
+  `redeemAccessToken(token, ctx)`, which upgrades the token before fetching the profile.
+  Credentials, tenant, and the egress-guarded `fetch` are injected; provider and HTTP failures
+  throw `OAuthProviderError` (`provider`, `kind`, `status`), while Microsoft ID-token
+  verification failures throw `OidcVerificationError` (`code`). Persistence and HTTP error
+  mapping stay in the application.
 - `collections`, `async`, and `stable-json`: collection deduplication/merging, bounded async mapping,
   and deterministic JSON serialization.
 - `feature-flags`: base64 JSON feature-flag cookie parsing and serialization with caller-injected

package/dist/feature-flags.d.mts

@@ -8,7 +8,7 @@ export type FeatureFlagCookieOptions = {
 };
 export declare const DEFAULT_FEATURE_FLAG_COOKIE_MAX_LENGTH = 4096;
 export declare function extractBooleanFeatureFlags(fields: Record<string, unknown>): FeatureFlags;
-export declare function parseFeatureFlagCookie(cookieValue: string, codec: FeatureFlagCookieCodec, options?: FeatureFlagCookieOptions): FeatureFlags;
+export declare function parseFeatureFlagCookie(cookieValue: string, codec: Partial<FeatureFlagCookieCodec> & Pick<FeatureFlagCookieCodec, 'decodeBase64'>, options?: FeatureFlagCookieOptions): FeatureFlags;
 export declare function encodeFeatureFlagCookie(overrides: FeatureFlags, codec: FeatureFlagCookieCodec): string;
 export declare function parseFeatureFlagCookieMaxLength(value: string | undefined, fallback?: number): number;
 export declare function safeFeatureFlagCookiePart(cookieName: string, cookieValue: string | undefined, options?: FeatureFlagCookieOptions): string | null;

package/dist/oauth-providers-facebook.d.mts

@@ -1,4 +1,4 @@
-import { type OAuthProvider } from './oauth-providers-core.mts';
+import { type OAuthCallContext, type OAuthProvider } from './oauth-providers-core.mts';
 export interface FacebookProviderConfig {
     appId: string;
     appSecret: string;
@@ -6,4 +6,6 @@ export interface FacebookProviderConfig {
     graphVersion: string;
 }
 /** Code exchange, then `fb_exchange_token` for a long-lived token, then `/me`. */
-export declare function facebookProvider(config: FacebookProviderConfig): OAuthProvider;
+export declare function facebookProvider(config: FacebookProviderConfig): OAuthProvider & {
+    redeemAccessToken(token: string, ctx: OAuthCallContext): ReturnType<OAuthProvider['redeem']>;
+};

package/dist/oauth-providers-facebook.mjs

@@ -7,21 +7,28 @@ export function facebookProvider(config) {
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
         body: formBody({ client_id: config.appId, client_secret: config.appSecret, ...values }),
     });
+    async function redeemAccessToken(token, ctx) {
+        if (!token) {
+            throw new OAuthProviderError('facebook', 'malformed', 'An access token is required');
+        }
+        const now = nowOf(ctx);
+        const tokens = parseTokens('facebook', await requestJson('facebook', 'Facebook token exchange', ctx, `${graph}/oauth/access_token`, form({ grant_type: 'fb_exchange_token', fb_exchange_token: token })), now);
+        const mePayload = await requestJson('facebook', 'Facebook /me request', ctx, `${graph}/me?fields=name,email`, { headers: { Authorization: `Bearer ${tokens.accessToken}` } });
+        const me = asRecord('facebook', mePayload, 'Facebook /me response');
+        const id = str(me.id);
+        if (!id)
+            throw new OAuthProviderError('facebook', 'malformed', 'Facebook user is missing id');
+        return {
+            tokens,
+            profile: { providerUserId: id, verifiedEmail: null, data: me },
+        };
+    }
     return {
         id: 'facebook',
         async redeem(input, ctx) {
-            const now = nowOf(ctx);
-            const shortLived = parseTokens('facebook', await requestJson('facebook', 'Facebook authorization code exchange', ctx, `${graph}/oauth/access_token`, form({ redirect_uri: input.redirectUri, code: input.code })), now);
-            const tokens = parseTokens('facebook', await requestJson('facebook', 'Facebook token exchange', ctx, `${graph}/oauth/access_token`, form({ grant_type: 'fb_exchange_token', fb_exchange_token: shortLived.accessToken })), now);
-            const mePayload = await requestJson('facebook', 'Facebook /me request', ctx, `${graph}/me?fields=name,email`, { headers: { Authorization: `Bearer ${tokens.accessToken}` } });
-            const me = asRecord('facebook', mePayload, 'Facebook /me response');
-            const id = str(me.id);
-            if (!id)
-                throw new OAuthProviderError('facebook', 'malformed', 'Facebook user is missing id');
-            return {
-                tokens,
-                profile: { providerUserId: id, verifiedEmail: str(me.email) ?? null, data: me },
-            };
+            const shortLived = parseTokens('facebook', await requestJson('facebook', 'Facebook authorization code exchange', ctx, `${graph}/oauth/access_token`, form({ redirect_uri: input.redirectUri, code: input.code })), nowOf(ctx));
+            return redeemAccessToken(shortLived.accessToken, ctx);
         },
+        redeemAccessToken,
     };
 }

package/dist/oauth-providers-microsoft.d.mts

@@ -4,11 +4,8 @@ export interface MicrosoftProviderConfig {
     clientSecret: string;
     /** Defaults to `common`. */
     tenantId?: string;
-    /**
-     * Treat Graph `mail` as verified. Off by default: a tenant admin can set `mail` without proving
-     * ownership, so only enable it when every accepted tenant is trusted.
-     */
-    trustMailAsVerified?: boolean;
 }
-/** v2.0 token exchange with required PKCE; Graph `mail` is unverified unless trusted. */
+/** Request these scopes in the authorization URL for ID-token email and Graph /me. */
+export declare const microsoftAuthorizationScopes = "openid email User.Read";
+/** v2.0 code exchange with PKCE, signed ID-token email proof, and Graph profile data. */
 export declare function microsoftProvider(config: MicrosoftProviderConfig): OAuthProvider;

package/dist/oauth-providers-microsoft.mjs

@@ -1,12 +1,18 @@
+import { createOidcIdTokenVerifier } from './oidc-id-token.mjs';
+import { microsoftProfileFromClaims } from './oidc-id-token-profiles.mjs';
 import { OAuthProviderError, asRecord, compact, formBody, nowOf, parseTokens, requestJson, requireCodeVerifier, str, } from './oauth-providers-core.mjs';
-/** v2.0 token exchange with required PKCE; Graph `mail` is unverified unless trusted. */
+const TENANT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Request these scopes in the authorization URL for ID-token email and Graph /me. */
+export const microsoftAuthorizationScopes = 'openid email User.Read';
+/** v2.0 code exchange with PKCE, signed ID-token email proof, and Graph profile data. */
 export function microsoftProvider(config) {
     return {
         id: 'microsoft',
         async redeem(input, ctx) {
             const codeVerifier = requireCodeVerifier('microsoft', input);
             const tenant = config.tenantId || 'common';
-            const tokenPayload = await requestJson('microsoft', 'Microsoft token exchange', ctx, `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`, {
+            const login = `https://login.microsoftonline.com/${tenant}`;
+            const tokenPayload = await requestJson('microsoft', 'Microsoft token exchange', ctx, `${login}/oauth2/v2.0/token`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                 body: formBody({
@@ -16,23 +22,50 @@ export function microsoftProvider(config) {
                     client_id: config.clientId,
                     client_secret: config.clientSecret,
                     code_verifier: codeVerifier,
+                    scope: microsoftAuthorizationScopes,
                 }),
             });
             const tokens = parseTokens('microsoft', tokenPayload, nowOf(ctx));
+            const body = asRecord('microsoft', tokenPayload, 'Microsoft token response');
+            const idToken = str(body.id_token);
+            if (!idToken) {
+                throw new OAuthProviderError('microsoft', 'malformed', 'Token response is missing id_token');
+            }
+            const alias = tenant === 'common' || tenant === 'organizations';
+            const verifier = createOidcIdTokenVerifier({
+                jwksUri: `${login}/discovery/v2.0/keys`,
+                issuers: [],
+                issuerMatches: (claims, keyIssuer) => {
+                    const tid = claims.tid;
+                    if (typeof tid !== 'string' || !TENANT_ID.test(tid))
+                        return false;
+                    const issuer = `https://login.microsoftonline.com/${tid}/v2.0`;
+                    return ((alias || tid === tenant) &&
+                        claims.iss === issuer &&
+                        (keyIssuer === undefined || keyIssuer.replace('{tenantid}', tid) === issuer));
+                },
+                audiences: () => [config.clientId],
+                fetch: ctx.fetch,
+                ...(ctx.now ? { now: ctx.now } : {}),
+            });
+            const claims = await verifier.verify(idToken, ctx.signal ? { signal: ctx.signal } : {});
             const mePayload = await requestJson('microsoft', 'Microsoft Graph /me request', ctx, 'https://graph.microsoft.com/v1.0/me', { headers: { Authorization: `Bearer ${tokens.accessToken}` } });
             const me = asRecord('microsoft', mePayload, 'Microsoft Graph /me response');
             const id = str(me.id);
             if (!id)
                 throw new OAuthProviderError('microsoft', 'malformed', 'Microsoft user is missing id');
-            const email = str(me.mail);
+            if (claims.oid !== id) {
+                throw new OAuthProviderError('microsoft', 'malformed', 'ID token user does not match Graph user');
+            }
+            const signedProfile = microsoftProfileFromClaims(claims);
             return {
                 tokens,
                 profile: {
                     providerUserId: id,
-                    verifiedEmail: config.trustMailAsVerified ? (email ?? null) : null,
+                    verifiedEmail: signedProfile.verifiedEmail,
                     data: compact({
                         name: str(me.displayName),
-                        email,
+                        email: str(me.mail),
                         given_name: str(me.givenName),
                         family_name: str(me.surname),
                     }),

package/dist/oauth-providers.d.mts

@@ -4,5 +4,5 @@ export { facebookProvider, type FacebookProviderConfig } from './oauth-providers
 export { githubProvider, type GithubProviderConfig } from './oauth-providers-github.mts';
 export { googleProvider, type GoogleProviderConfig } from './oauth-providers-google.mts';
 export { linkedinProvider, type LinkedinProviderConfig } from './oauth-providers-linkedin.mts';
-export { microsoftProvider, type MicrosoftProviderConfig } from './oauth-providers-microsoft.mts';
+export { microsoftAuthorizationScopes, microsoftProvider, type MicrosoftProviderConfig, } from './oauth-providers-microsoft.mts';
 export { xProvider, type XProviderConfig } from './oauth-providers-x.mts';

package/dist/oauth-providers.mjs

@@ -3,5 +3,5 @@ export { facebookProvider } from './oauth-providers-facebook.mjs';
 export { githubProvider } from './oauth-providers-github.mjs';
 export { googleProvider } from './oauth-providers-google.mjs';
 export { linkedinProvider } from './oauth-providers-linkedin.mjs';
-export { microsoftProvider } from './oauth-providers-microsoft.mjs';
+export { microsoftAuthorizationScopes, microsoftProvider, } from './oauth-providers-microsoft.mjs';
 export { xProvider } from './oauth-providers-x.mjs';

package/dist/oidc-id-token-profiles.d.mts

@@ -15,6 +15,8 @@ export interface OidcClaims {
     [claim: string]: unknown;
 }
 export declare function googleProfileFromClaims(claims: OidcClaims): OAuthProfile;
+/** Microsoft verifies an email only when the signed domain-owner claim is boolean true. */
+export declare function microsoftProfileFromClaims(claims: OidcClaims): OAuthProfile;
 /** Apple sends `email_verified` as a boolean or the string `'true'`. */
 export declare function appleProfileFromClaims(claims: OidcClaims, userData?: {
     name?: string;

package/dist/oidc-id-token-profiles.mjs

@@ -13,6 +13,20 @@ export function googleProfileFromClaims(claims) {
         data,
     };
 }
+/** Microsoft verifies an email only when the signed domain-owner claim is boolean true. */
+export function microsoftProfileFromClaims(claims) {
+    const data = {};
+    for (const key of ['name', 'email', 'given_name', 'family_name']) {
+        if (claims[key])
+            data[key] = claims[key];
+    }
+    const oid = claims.oid;
+    return {
+        providerUserId: typeof oid === 'string' && oid.length > 0 ? oid : claims.sub,
+        verifiedEmail: claims.xms_edov === true ? (claims.email ?? null) : null,
+        data,
+    };
+}
 /** Apple sends `email_verified` as a boolean or the string `'true'`. */
 export function appleProfileFromClaims(claims, userData) {
     const data = {};

package/dist/oidc-id-token.d.mts

@@ -1,6 +1,6 @@
 import type { OAuthFetch } from './oauth-types.mts';
 import type { OidcClaims } from './oidc-id-token-profiles.mts';
-export { appleProfileFromClaims, googleProfileFromClaims, type OidcClaims, } from './oidc-id-token-profiles.mts';
+export { appleProfileFromClaims, googleProfileFromClaims, microsoftProfileFromClaims, type OidcClaims, } from './oidc-id-token-profiles.mts';
 export type OidcVerificationCode = 'format' | 'alg' | 'key_not_found' | 'signature' | 'expired' | 'future_iat' | 'not_yet_valid' | 'issuer' | 'audience' | 'nonce' | 'nonce_missing' | 'jwks_fetch';
 export declare class OidcVerificationError extends Error {
     readonly code: OidcVerificationCode;
@@ -9,6 +9,8 @@ export declare class OidcVerificationError extends Error {
 export interface OidcIdTokenVerifierOptions {
     jwksUri: string;
     issuers: readonly string[];
+    /** Additional issuer rule evaluated only after the token signature is verified. */
+    issuerMatches?: (claims: OidcClaims, keyIssuer?: string) => boolean;
     /** Read on every verification so configuration can change at runtime. */
     audiences: () => readonly string[];
     fetch: OAuthFetch;

package/dist/oidc-id-token.mjs

@@ -1,6 +1,6 @@
 import { createHash, createPublicKey, createVerify } from 'node:crypto';
 import { abortable } from './oidc-id-token-util.mjs';
-export { appleProfileFromClaims, googleProfileFromClaims, } from './oidc-id-token-profiles.mjs';
+export { appleProfileFromClaims, googleProfileFromClaims, microsoftProfileFromClaims, } from './oidc-id-token-profiles.mjs';
 export class OidcVerificationError extends Error {
     code;
     constructor(code, message) {
@@ -84,7 +84,7 @@ export function createOidcIdTokenVerifier(options) {
         if (!valid)
             throw new OidcVerificationError('signature', 'ID token signature is invalid');
     }
-    function checkClaims(claims, verify) {
+    function checkClaims(claims, verify, key) {
         if (typeof claims.exp !== 'number' || typeof claims.iat !== 'number') {
             throw new OidcVerificationError('format', 'ID token is missing exp or iat');
         }
@@ -103,7 +103,7 @@ export function createOidcIdTokenVerifier(options) {
         if (claims.nbf !== undefined && claims.nbf > seconds + skew) {
             throw new OidcVerificationError('not_yet_valid', 'ID token is not valid yet');
         }
-        if (!options.issuers.includes(claims.iss)) {
+        if (!options.issuers.includes(claims.iss) && !options.issuerMatches?.(claims, key.issuer)) {
             throw new OidcVerificationError('issuer', 'ID token issuer is invalid');
         }
         const accepted = options.audiences();
@@ -134,7 +134,7 @@ export function createOidcIdTokenVerifier(options) {
             const key = await findKey(kid, verify.signal);
             checkSignature(`${header}.${payload}`, signature, key);
             const claims = decodePart(payload);
-            checkClaims(claims, verify);
+            checkClaims(claims, verify, key);
             return claims;
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {