IdentityFlow.Tooling.Playwright 0.1.0-alpha.20260722083539

IdentityFlow.Tooling.Playwright

Playwright helpers for test agents that need reusable IdentityFlow passkeys and authenticator app codes.

This package is for development, CI, and automated test agents. Do not use it as production credential storage.

What This Package Does

• Adds a Chromium virtual WebAuthn authenticator to a Playwright IPage.
• Restores cached virtual passkey credentials into that authenticator.
• Captures newly enrolled virtual passkey credentials back into the cache.
• Stores TOTP enrollment secrets and generates current authenticator app codes.
• Persists an explicit local cache file for agent reuse across test runs.

Passkeys are not just a cache lookup. The browser must have a WebAuthn authenticator available when the app calls navigator.credentials.create() or navigator.credentials.get(). This package supplies that browser interoperability through Playwright plus Chrome DevTools Protocol.

Install

Reference the library from a Playwright test project:

<PackageReference Include="IdentityFlow.Tooling.Playwright" Version="0.1.0" />

For local source development, reference the project:

<ProjectReference Include="src/Tooling/IdentityFlow.Tooling.Playwright/IdentityFlow.Tooling.Playwright.csproj" />

Cache File

Use a local cache path such as:

.identityflow-agent-auth/local.json

The .identityflow-agent-auth/ directory is already ignored by this repository's root .gitignore. In downstream projects, add the cache directory to your own .gitignore or, preferably, keep the cache path outside the repository. The cache can contain virtual passkey private keys and TOTP shared secrets. Files are created as owner-readable/writable on Unix-like systems. Use IIdentityFlowAgentAuthCacheProtector when a host wants encryption or another at-rest protection mechanism.

Passkey Sign-In Flow

The library must run inside the Playwright test process because it needs the active IPage.

await using IdentityFlowPlaywrightAuthAgent auth =
    await IdentityFlowPlaywrightAuthAgent.LoadAsync(
        page,
        ".identityflow-agent-auth/local.json");

bool restored = await auth.RestorePasskeyAsync(
    origin: "http://localhost:5000",
    relyingPartyId: "localhost",
    identityId: "alice@example.com");

if (restored)
{
    await page.GetByRole(AriaRole.Button, new() { Name = "Sign in with passkey" }).ClickAsync();
}

When the app calls navigator.credentials.get(), Chromium answers with the restored virtual credential.

Passkey Enrollment Flow

Attach an authenticator before clicking the app's passkey enrollment UI. After the ceremony completes, capture and save the generated credential.

await using IdentityFlowPlaywrightAuthAgent auth =
    await IdentityFlowPlaywrightAuthAgent.LoadAsync(
        page,
        ".identityflow-agent-auth/local.json");

await auth.AttachPasskeyAuthenticatorAsync(WebAuthnVirtualAuthenticatorOptions.PlatformPasskey);

await page.GetByRole(AriaRole.Button, new() { Name = "Create passkey" }).ClickAsync();

await auth.CapturePasskeyAsync(
    origin: "http://localhost:5000",
    relyingPartyId: "localhost",
    identityId: "alice@example.com");

await auth.SaveAsync();

TOTP Enrollment And Sign-In

IdentityFlow returns a TOTP setup URI during authenticator app enrollment. Cache it once, then generate fresh codes later.

auth.CacheTotpSecret(
    origin: "http://localhost:5000",
    identityId: "alice@example.com",
    setupUri: setupUriFromEnrollment);

await auth.SaveAsync();

string? code = await auth.GetCurrentTotpCodeAsync(
    origin: "http://localhost:5000",
    identityId: "alice@example.com");

await page.GetByLabel("Authenticator code").FillAsync(code!);
await page.GetByRole(AriaRole.Button, new() { Name = "Verify" }).ClickAsync();

Low-Level WebAuthn API

Use WebAuthnVirtualAuthenticator directly when you want full control over the browser authenticator.

await using WebAuthnVirtualAuthenticator authenticator =
    await WebAuthnVirtualAuthenticator.AttachAsync(page, WebAuthnVirtualAuthenticatorOptions.PlatformPasskey);

await authenticator.SetUserVerifiedAsync(true);
await authenticator.AddCredentialsAsync(cachedCredentials);

IReadOnlyList<WebAuthnCachedCredential> credentials = await authenticator.GetCredentialsAsync();

CLI Companion

The companion .NET tool is IdentityFlow.Tooling.Playwright.Cli:

dotnet tool install --global IdentityFlow.Tooling.Playwright.Cli

Use it to inspect caches, clear entries, and generate TOTP codes:

identityflow-auth-cache list --cache .identityflow-agent-auth/local.json

identityflow-auth-cache totp current \
  --cache .identityflow-agent-auth/local.json \
  --origin http://localhost:5000 \
  --user alice@example.com

Prefer --otpauth-stdin or --secret-stdin for totp add so TOTP secrets do not appear in shell history, process listings, CI command echoing, or logs.

The CLI does not perform passkey login in an already-running Playwright browser. Passkey login requires the library so a test can attach a virtual authenticator to the active IPage.

Limits

• WebAuthn automation uses Chromium CDP and is Chromium-focused.
• Virtual authenticators test WebAuthn ceremony correctness, not OS UX such as Touch ID, Windows Hello, iCloud Keychain, or phone-based hybrid flows.
• TOTP cache entries store shared secrets, not generated one-time codes.