@chipmobilesdk/rn-auth 0.3.0 → 0.3.1

package/package.json

@@ -1,54 +1,51 @@
-{
-	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.3.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/core",
-		"src/tokens",
-		"src/oidc",
-		"src/access",
-		"src/diagnostics",
-		"src/react",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-app-auth": ">=8",
-		"react-native-keychain": ">=10"
-	},
-	"peerDependenciesMeta": {
-		"react-native-app-auth": {
-			"optional": true
-		},
-		"react-native-keychain": {
-			"optional": true
-		}
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-auth",
+	"version": "0.3.1",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/tokens",
+		"src/oidc",
+		"src/access",
+		"src/diagnostics",
+		"src/react",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-app-auth": ">=8",
+		"react-native-keychain": ">=10"
+	},
+	"peerDependenciesMeta": {
+		"react-native-app-auth": {
+			"optional": true
+		},
+		"react-native-keychain": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-auth/SKILL.md

@@ -1,63 +1,62 @@
----
-name: sdk-rn-auth
-description: "Authentication via @chipmobilesdk/rn-auth: OIDC/AppAuth login, keychain token storage, access tiers, auth error handling. Use when wiring sign-in, storing tokens securely, gating features by tier, or configuring a tenant/provider."
-metadata:
-  package: "@chipmobilesdk/rn-auth"
-  packageVersion: "0.2.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-auth
-
-OIDC authentication with secure token storage and an access-tier model for
-feature gating.
-
-## Use this when
-
-- Wiring sign-in / sign-out
-- Persisting tokens (must be keychain, never plain storage)
-- Gating a feature on the user's access tier
-- Mapping an auth failure to a user-facing message
-- Onboarding a new tenant or identity provider
-
-## Configuration is a contract, not options
-
-Tenant and provider setup has prerequisites that fail at runtime, not at build time.
-Before configuring anything, walk `## Configuration contract (LIB-010)` and
-`## Tenant / provider prerequisite checklist (LIB-018)` in the README. Skipping the
-checklist is the usual cause of "login works locally, fails in the new environment".
-
-## Fail closed
-
-`failClosedTier` exists because an unknown tier must deny access, not grant it. When
-tier evaluation is unavailable, deny. Never default an unresolved tier to a permissive
-value.
-
-## Public API (v0.3.0)
-
-Runtime:
-
-- `createAppAuthClient(...)` — the OIDC client
-- `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
-- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
-- `AuthProvider` — React context provider
-
-Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
-`AuthMessageMap`, `AuthMessageKey`
-
-`AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
-only — never render a diagnostic-audience message in the UI.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install (consuming app)`, `## Quick start` |
-| Required config fields | `## Configuration contract (LIB-010)` |
-| New tenant or IdP | `## Tenant / provider prerequisite checklist (LIB-018)` |
-| Token handling, logging rules | `## Security & privacy` |
-| Full export list | `## Public API` |
-| Version/peer constraints | `## Compatibility and validation` |
+---
+name: sdk-rn-auth
+description: "Authentication via @chipmobilesdk/rn-auth: OIDC/AppAuth login, keychain token storage, access tiers, auth error handling. Use when wiring sign-in, storing tokens securely, gating features by tier, or configuring a tenant/provider."
+metadata:
+  package: "@chipmobilesdk/rn-auth"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-auth
+
+OIDC authentication with secure token storage and an access-tier model for
+feature gating.
+
+## Use this when
+
+- Wiring sign-in / sign-out
+- Persisting tokens (must be keychain, never plain storage)
+- Gating a feature on the user's access tier
+- Mapping an auth failure to a user-facing message
+- Onboarding a new tenant or identity provider
+
+## Configuration is a contract, not options
+
+Tenant and provider setup has prerequisites that fail at runtime, not at build time.
+Before configuring anything, walk `## Configuration contract (LIB-010)` and
+`## Tenant / provider prerequisite checklist (LIB-018)` in the README. Skipping the
+checklist is the usual cause of "login works locally, fails in the new environment".
+
+## Fail closed
+
+`failClosedTier` exists because an unknown tier must deny access, not grant it. When
+tier evaluation is unavailable, deny. Never default an unresolved tier to a permissive
+value.
+
+## Public API
+
+Runtime:
+
+- `createAppAuthClient(...)` — the OIDC client
+- `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
+- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
+- `AuthProvider` — React context provider
+
+Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
+`AuthMessageMap`, `AuthMessageKey`
+
+`AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
+only — never render a diagnostic-audience message in the UI.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install (consuming app)`, `## Quick start` |
+| Required config fields | `## Configuration contract (LIB-010)` |
+| New tenant or IdP | `## Tenant / provider prerequisite checklist (LIB-018)` |
+| Token handling, logging rules | `## Security & privacy` |
+| Full export list | `## Public API` |
+| Version/peer constraints | `## Compatibility and validation` |

package/src/access/accessTier.ts

@@ -1,88 +1,88 @@
-/**
- * Access-tier evaluation (FR-010/FR-011/FR-019/FR-020, R6).
- *
- * Pure function over the authenticated token's claims and the app-specific
- * mapping. Object ids are authoritative; display names never grant access.
- * Missing, stale, ambiguous, or group-overage claims fail closed (premium
- * denied, verification = 'unverified').
- */
-
-import type { AccessTier, AccessTierMapping, ClaimMatcher } from '../config/types';
-
-/** The fail-closed default: free + unverified. */
-export function failClosedTier(): AccessTier {
-	return { tier: 'free', source: 'default', verification: 'unverified' };
-}
-
-function toStringArray(value: unknown): string[] {
-	if (Array.isArray(value)) {
-		return value.filter((entry): entry is string => typeof entry === 'string');
-	}
-	if (typeof value === 'string') {
-		return [value];
-	}
-	return [];
-}
-
-/**
- * Entra emits a groups overage indicator (`_claim_names.groups` or `hasgroups`)
- * instead of inline groups when the list is too large. Reading the full list
- * would require Graph (out of scope, FR-012), so overage fails closed.
- */
-function hasGroupOverage(claims: Record<string, unknown>): boolean {
-	if (claims.hasgroups === true) {
-		return true;
-	}
-	const claimNames = claims._claim_names as Record<string, unknown> | undefined;
-	if (claimNames && typeof claimNames === 'object' && 'groups' in claimNames) {
-		return true;
-	}
-	return false;
-}
-
-function matchesClaim(claims: Record<string, unknown>, matcher: ClaimMatcher): boolean {
-	const value = claims[matcher.claim];
-	if (Array.isArray(value)) {
-		return value.includes(matcher.equals);
-	}
-	return value === matcher.equals;
-}
-
-/** Evaluate the access tier, failing closed when entitlement is unverifiable. */
-export function evaluateAccessTier(
-	claims: Record<string, unknown>,
-	mapping: AccessTierMapping,
-	now: number = Date.now(),
-): AccessTier {
-	// Object ids first (authoritative). Display names are never consulted.
-	const groups = toStringArray(claims.groups);
-	if (
-		mapping.premiumGroupObjectIds.length > 0 &&
-		groups.some(group => mapping.premiumGroupObjectIds.includes(group))
-	) {
-		return { tier: 'premium', source: 'group', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// Roles next.
-	const roles = toStringArray(claims.roles);
-	if (
-		mapping.premiumRoleNames?.length &&
-		roles.some(role => mapping.premiumRoleNames!.includes(role))
-	) {
-		return { tier: 'premium', source: 'role', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// Custom claim matchers last.
-	if (mapping.premiumClaimMatchers?.some(matcher => matchesClaim(claims, matcher))) {
-		return { tier: 'premium', source: 'claim', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// No premium indicator matched. If group claims are unavailable due to
-	// overage and premium depends on groups, we cannot verify → fail closed.
-	if (mapping.premiumGroupObjectIds.length > 0 && hasGroupOverage(claims)) {
-		return { tier: 'free', source: 'default', verification: 'unverified', lastRefreshAt: now };
-	}
-
-	// Verified free: claims were present and simply did not grant premium.
-	return { tier: 'free', source: 'default', verification: 'verified', lastRefreshAt: now };
-}
+/**
+ * Access-tier evaluation (FR-010/FR-011/FR-019/FR-020, R6).
+ *
+ * Pure function over the authenticated token's claims and the app-specific
+ * mapping. Object ids are authoritative; display names never grant access.
+ * Missing, stale, ambiguous, or group-overage claims fail closed (premium
+ * denied, verification = 'unverified').
+ */
+
+import type { AccessTier, AccessTierMapping, ClaimMatcher } from '../config/types';
+
+/** The fail-closed default: free + unverified. */
+export function failClosedTier(): AccessTier {
+	return { tier: 'free', source: 'default', verification: 'unverified' };
+}
+
+function toStringArray(value: unknown): string[] {
+	if (Array.isArray(value)) {
+		return value.filter((entry): entry is string => typeof entry === 'string');
+	}
+	if (typeof value === 'string') {
+		return [value];
+	}
+	return [];
+}
+
+/**
+ * Entra emits a groups overage indicator (`_claim_names.groups` or `hasgroups`)
+ * instead of inline groups when the list is too large. Reading the full list
+ * would require Graph (out of scope, FR-012), so overage fails closed.
+ */
+function hasGroupOverage(claims: Record<string, unknown>): boolean {
+	if (claims.hasgroups === true) {
+		return true;
+	}
+	const claimNames = claims._claim_names as Record<string, unknown> | undefined;
+	if (claimNames && typeof claimNames === 'object' && 'groups' in claimNames) {
+		return true;
+	}
+	return false;
+}
+
+function matchesClaim(claims: Record<string, unknown>, matcher: ClaimMatcher): boolean {
+	const value = claims[matcher.claim];
+	if (Array.isArray(value)) {
+		return value.includes(matcher.equals);
+	}
+	return value === matcher.equals;
+}
+
+/** Evaluate the access tier, failing closed when entitlement is unverifiable. */
+export function evaluateAccessTier(
+	claims: Record<string, unknown>,
+	mapping: AccessTierMapping,
+	now: number = Date.now(),
+): AccessTier {
+	// Object ids first (authoritative). Display names are never consulted.
+	const groups = toStringArray(claims.groups);
+	if (
+		mapping.premiumGroupObjectIds.length > 0 &&
+		groups.some(group => mapping.premiumGroupObjectIds.includes(group))
+	) {
+		return { tier: 'premium', source: 'group', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// Roles next.
+	const roles = toStringArray(claims.roles);
+	if (
+		mapping.premiumRoleNames?.length &&
+		roles.some(role => mapping.premiumRoleNames!.includes(role))
+	) {
+		return { tier: 'premium', source: 'role', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// Custom claim matchers last.
+	if (mapping.premiumClaimMatchers?.some(matcher => matchesClaim(claims, matcher))) {
+		return { tier: 'premium', source: 'claim', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// No premium indicator matched. If group claims are unavailable due to
+	// overage and premium depends on groups, we cannot verify → fail closed.
+	if (mapping.premiumGroupObjectIds.length > 0 && hasGroupOverage(claims)) {
+		return { tier: 'free', source: 'default', verification: 'unverified', lastRefreshAt: now };
+	}
+
+	// Verified free: claims were present and simply did not grant premium.
+	return { tier: 'free', source: 'default', verification: 'verified', lastRefreshAt: now };
+}