@wcstack/credential 1.20.0 → 1.21.0

package/README.ja.md

@@ -61,6 +61,11 @@ npm install @wcstack/credential
 | `loading`   | `wcs-credential:loading-changed`    | `get()`/`store()`呼び出し中は`true`。 |
 | `error`     | `wcs-credential:error`              | 真のプラットフォーム失敗（正規化された`{ name, message }`）、無ければ`null`。 |
 | `cancelled` | `wcs-credential:cancelled-changed`  | ユーザーがブラウザのアカウント選択UIを閉じたら`true`（Credential Management APIは`NotAllowedError`でrejectする）。`error`には含めない。 |
+| `errorInfo` | `wcs-credential:error-info-changed` | serializable な失敗 taxonomy（安定 `code` / `phase` / `recoverable`）、または `null`。追加的で `error` の shape は不変。`code` は `capability-missing`（unsupported）・`out-of-scope`（`publicKey`/WebAuthn 試行）・`credential-failed`（真の失敗）。`NotAllowedError` のキャンセルは `cancelled` であり `errorInfo` ではない。 |
+
+**並行制御。** `get()` と `store()` は 1 つの io-core lane を `latest` policy で共有する:
+後発の呼び出しが先発を **supersede** する（実際の認証フローでは順次利用される — ログイン後に
+store、その前に get — 並行ではない）。並行実行時は後発の結果が勝つ。
 
 ## コマンド
 

package/README.md

@@ -62,6 +62,12 @@ npm install @wcstack/credential
 | `loading`   | `wcs-credential:loading-changed` | `true` while a `get()`/`store()` call is in flight. |
 | `error`     | `wcs-credential:error`           | A true platform failure (normalized `{ name, message }`), or `null`. |
 | `cancelled` | `wcs-credential:cancelled-changed` | `true` when the user dismissed the browser's account-chooser UI (the Credential Management API rejects with `NotAllowedError`). Kept out of `error`. |
+| `errorInfo` | `wcs-credential:error-info-changed` | Serializable failure taxonomy (stable `code` / `phase` / `recoverable`), or `null`. Additive — the `error` shape is unchanged; `code` is `capability-missing` (unsupported), `out-of-scope` (a `publicKey`/WebAuthn attempt), or `credential-failed` (a genuine failure). A `NotAllowedError` cancellation is `cancelled`, not `errorInfo`. |
+
+**Concurrency.** `get()` and `store()` share one io-core lane with the `latest`
+policy: a later call **supersedes** the earlier one (these are used sequentially in
+real auth flows — store after login, get before one — not concurrently). If both
+are invoked concurrently, the later call's result wins.
 
 ## Commands
 

package/dist/index.d.ts

@@ -1,3 +1,56 @@
+/**
+ * platform-capability.ts
+ *
+ * Phase 6(docs/architecture-hardening/09-remediation-design.md §7.2 /
+ * 07-browser-capability-variance.md)の browser capability 判定と error taxonomy の
+ * 汎用プリミティブ。node 固有の capability registry / error code は各パッケージが
+ * 別ファイルで宣言し、この汎用層(型 + assess 機構)を import する。
+ *
+ * 原則:
+ * - feature detection は境界(利用直前)で行う。module 評価時に browser global を
+ *   参照しない(SSR / worker で import が失敗しない)。
+ * - capability ID(`web.fetch` 等)は文字列を global property path として eval せず、
+ *   registry が ID ごとに副作用のない presence probe を対応付ける。
+ * - availability / permission / readiness / activity / operation error を 1 つの
+ *   `ready / unsupported / error` enum に畳まない。required 欠如は開始しない、
+ *   optional 欠如は宣言済み fallback で readiness を `degraded` にする。
+ *
+ * 配置: 本ファイルは /io-core/ の単一正典であり、scripts/sync-io-core.mjs が
+ * 各 IO ノードの src/core/ へ生成コピー (AUTO-GENERATED, 編集禁止) を配布する。
+ * `protocol/wcBindable.ts` と同じ copy-distribution 方式で、ランタイム依存を導入せず
+ * 各パッケージのバンドルへ inline される (zero-runtime-dep / 自己完結 CDN を維持)。
+ * 編集はこの正典に対して行い、`node scripts/sync-io-core.mjs` で再配布する。
+ *
+ * pure(module 評価時に browser global 非参照)。
+ */
+type Availability = "available" | "missing" | "unknown";
+type PermissionState = "granted" | "denied" | "prompt" | "not-applicable" | "unknown";
+type Readiness = "idle" | "ready" | "degraded";
+type Activity = "inactive" | "active";
+type PreconditionState = "satisfied" | "required" | "not-applicable";
+/** operation error の phase(taxonomy)。 */
+type WcsIoErrorPhase = "probe" | "start" | "execute" | "decode" | "commit" | "dispose";
+/** serializable な error info(non-cloneable な cause とは分離。DevTools / remote へは info のみ)。 */
+interface WcsIoErrorInfo {
+    readonly code: string;
+    readonly phase: WcsIoErrorPhase;
+    readonly recoverable: boolean;
+    readonly capabilityId?: string;
+    readonly message: string;
+}
+interface PlatformAssessment {
+    readonly availability: ReadonlyMap<string, Availability>;
+    readonly permission: PermissionState;
+    readonly readiness: Readiness;
+    readonly activity: Activity;
+    readonly preconditions: {
+        readonly secureContext: PreconditionState;
+        readonly userActivation: PreconditionState;
+    };
+    readonly epoch: number;
+    readonly lastError?: WcsIoErrorInfo;
+}
+
 interface IWcBindableProperty {
     readonly name: string;
     readonly event: string;
@@ -13,7 +66,8 @@ interface IWcBindableCommand {
 }
 interface IWcBindable {
     readonly protocol: "wc-bindable";
-    readonly version: 1;
+    /** Integer protocol version. All versions >= 1 are core-compatible. */
+    readonly version: number;
     readonly properties: readonly IWcBindableProperty[];
     readonly inputs?: readonly IWcBindableInput[];
     readonly commands?: readonly IWcBindableCommand[];
@@ -60,6 +114,7 @@ interface WcsCredentialCoreValues {
     loading: boolean;
     error: any;
     cancelled: boolean;
+    errorInfo: WcsIoErrorInfo | null;
 }
 /**
  * Value types for the Shell (`<wcs-credential>`) — identical observable
@@ -72,37 +127,41 @@ declare function bootstrapCredential(userConfig?: IWritableConfig): void;
 declare function getConfig(): IConfig;
 
 /**
- * Headless Credential Management primitive. A thin, framework-agnostic
- * wrapper around `navigator.credentials.get()`/`.store()` exposed through the
- * wc-bindable protocol.
+ * Headless Credential Management primitive. A thin, framework-agnostic wrapper
+ * around `navigator.credentials.get()`/`.store()` exposed through the wc-bindable
+ * protocol.
  *
- * Reuses batch3's "thin command" archetype established by `@wcstack/share`
- * (docs/credential-tag-design.md): single `_gen` generation guard,
- * same-value-guarded private setters, never-throw try/catch, no
- * `AbortController`/`abort()` command.
+ * Concurrency is owned by the shared `OperationLane` (io-core) with the `latest`
+ * policy — **`get()` and `store()` share one lane**. A later call supersedes the
+ * earlier one (the earlier completion fails the terminal CAS), preserving the v1
+ * "single generation" behavior (docs/multi-promise-io-node-design.md): these two
+ * operations are used sequentially in real auth flows (store after login, get
+ * before one), not naturally concurrently on the same instance. If both ARE
+ * invoked concurrently, the later call's result wins; use two separate
+ * `<wcs-credential>` instances if that bites. The lane runs with
+ * `withSignal: false` — the Credential Management API takes no `AbortSignal`;
+ * dispose() invalidates any in-flight call via the owner generation.
  *
- * **v1 scope excludes WebAuthn (`publicKey`)** — see docs/credential-tag-design.md
- * §0. `get()` validates and strips a `publicKey` option rather than silently
- * forwarding it, surfacing the attempt as a scope-violation `error` instead of
- * accidentally supporting WebAuthn through a side door.
+ * **v1 scope excludes WebAuthn (`publicKey`)** (docs/credential-tag-design.md §0):
+ * `get()` validates+strips a `publicKey` option and `store()` rejects a
+ * `PublicKeyCredential`, surfacing the attempt as a scope-violation `error`
+ * (`errorInfo.code === "out-of-scope"`) rather than a WebAuthn backdoor.
  *
- * **`get()`/`store()` share one `_gen`** — an accepted v1 simplification
- * (docs/multi-promise-io-node-design.md): these two operations are used
- * sequentially in real auth flows (store after a successful login, get before
- * attempting one), not naturally concurrently on the same instance. If both
- * ARE invoked concurrently on the same `<wcs-credential>`, the later call's
- * generation bump silently drops the earlier call's completion write. If this
- * limitation actually bites, use two separate `<wcs-credential>` instances
- * (one for get, one for store) rather than reworking the Core.
+ * Note the cancellation signal is **`NotAllowedError`, NOT `AbortError`**: unlike
+ * Web Share / Contact Picker, `credentials.get()/store()` reject with
+ * `NotAllowedError` when the user dismisses the native chooser. That maps to
+ * `cancelled`; every other name flows to `error`/`errorInfo`.
  */
 declare class CredentialCore extends EventTarget {
     static wcBindable: IWcBindable;
+    private static readonly REQUIRED_CAPABILITIES;
     private _target;
     private _value;
     private _loading;
     private _error;
     private _cancelled;
-    private _gen;
+    private _errorInfo;
+    private _lane;
     private _ready;
     constructor(target?: EventTarget);
     get ready(): Promise<void>;
@@ -110,37 +169,52 @@ declare class CredentialCore extends EventTarget {
     get loading(): boolean;
     get error(): any;
     get cancelled(): boolean;
+    /**
+     * The last failure's serializable `WcsIoErrorInfo` (stable `code` / `phase` /
+     * `recoverable` / `capabilityId`), or null. Exposed as an additive wc-bindable
+     * property (event `wcs-credential:error-info-changed`); the existing `error`
+     * property/event are unchanged. A `NotAllowedError` user cancellation is
+     * `cancelled`, not `errorInfo`.
+     */
+    get errorInfo(): WcsIoErrorInfo | null;
+    /**
+     * Whether the required platform capability (`web.credentials`) is available right
+     * now — decided by call-time feature detection, not User-Agent. Core-only,
+     * additive.
+     */
+    get supported(): boolean;
+    /**
+     * Full platform assessment (availability / readiness / preconditions), probed at
+     * call time. Core-only opt-in dev / sidecar view.
+     */
+    get platformAssessment(): PlatformAssessment;
     observe(): Promise<void>;
     dispose(): void;
+    private _commitStep;
     private _setLoading;
     private _setValue;
     private _setError;
     private _setCancelled;
-    private _api;
+    private _setErrorInfo;
+    private _commitErrorInfo;
     private _normalizeError;
     private _isCancellation;
+    private _run;
     /**
-     * `get(options)` — v1 scope excludes `publicKey` (WebAuthn). If present, it
-     * is stripped and the call surfaces a scope-violation `error` instead of
-     * forwarding it to the platform API (which would accidentally support
-     * WebAuthn through a side door). `navigator.credentials.get()` does not
-     * require a user gesture (unlike Web Share/Fullscreen), so this can be
-     * invoked automatically on page load for a "silent sign-in" flow.
+     * `get(options)` — v1 scope excludes `publicKey` (WebAuthn). If present, it is
+     * stripped and the call surfaces a scope-violation `error` instead of forwarding
+     * it to the platform API. `navigator.credentials.get()` does not require a user
+     * gesture, so this can be invoked automatically on page load for silent sign-in.
      */
     get(options?: CredentialGetOptions & {
         publicKey?: unknown;
     }): Promise<Credential | null>;
     /**
-     * `store(credential)` — shares the same single `_gen` as `get()` (see class
-     * docs). `navigator.credentials.store()` resolves `Promise<void>` (per
-     * `lib.dom.d.ts`) — there is no payload to read off the API, so `value` is
-     * synthesized as an echo of the caller's `credential`, mirroring
-     * `ShareCore.share()`'s same accommodation for `navigator.share()`.
-     *
-     * A `PublicKeyCredential` (`type === "public-key"`, WebAuthn) is rejected as a
-     * scope violation before touching the platform API — the same v1 boundary
-     * `get()` enforces on the `publicKey` option (docs/credential-tag-design.md
-     * §3.2), so this node never becomes a WebAuthn store backdoor.
+     * `store(credential)` — shares the same single lane as `get()`.
+     * `navigator.credentials.store()` resolves `Promise<void>`, so `value` is
+     * synthesized as an echo of the caller's `credential`. A `PublicKeyCredential`
+     * (`type === "public-key"`, WebAuthn) is rejected as a scope violation before
+     * touching the platform API.
      */
     store(credential: StorableCredential): Promise<Credential | null>;
 }
@@ -167,6 +241,7 @@ declare class WcsCredential extends HTMLElement {
     get loading(): boolean;
     get error(): any;
     get cancelled(): boolean;
+    get errorInfo(): WcsIoErrorInfo | null;
     get connectedCallbackPromise(): Promise<void>;
     get(options?: CredentialGetOptions): Promise<Credential | null>;
     store(credential: StorableCredential): Promise<Credential | null>;
@@ -174,5 +249,23 @@ declare class WcsCredential extends HTMLElement {
     disconnectedCallback(): void;
 }
 
-export { CredentialCore, WcsCredential, bootstrapCredential, getConfig };
-export type { CredentialGetOptions, IWritableConfig, IWritableTagNames, StorableCredential, WcsCredentialCoreValues, WcsCredentialValues };
+/**
+ * credentialCapabilities.ts
+ *
+ * Credential Management node 固有の capability registry と error code。汎用の assess
+ * 機構・型は `./platformCapability.js`(/io-core/ から copy-distribution される生成
+ * ファイル)から import する。node 固有の宣言はこのハンドライトファイルに置き、生成
+ * コピーとは分離する。
+ */
+
+/** 安定した credential error code(taxonomy)。値は公開キーとして固定。 */
+declare const WCS_CREDENTIAL_ERROR_CODE: {
+    readonly CapabilityMissing: "capability-missing";
+    /** WebAuthn(publicKey) は v1 スコープ外 — get()/store() 双方で拒否する。 */
+    readonly OutOfScope: "out-of-scope";
+    /** get()/store() の真のプラットフォーム失敗(NotAllowedError=cancelled は除く)。 */
+    readonly CredentialFailed: "credential-failed";
+};
+
+export { CredentialCore, WCS_CREDENTIAL_ERROR_CODE, WcsCredential, bootstrapCredential, getConfig };
+export type { CredentialGetOptions, IWritableConfig, IWritableTagNames, StorableCredential, WcsCredentialCoreValues, WcsCredentialValues, WcsIoErrorInfo, WcsIoErrorPhase };