feat(webauthn): make rpId the first argument of credentials.create() (#41259)

Author: dgozman

docs/src/api/class-credentials.md

@@ -20,8 +20,7 @@ There are two common ways to use it:
 const context = await browser.newContext();
 
 // A passkey your backend already provisioned for a test user.
-await context.credentials.create({
-  rpId: 'example.com',
+await context.credentials.create('example.com', {
   id: knownCredentialId, // base64url
   userHandle: knownUserHandle, // base64url
   privateKey: knownPrivateKey, // base64url PKCS#8 (DER)
@@ -54,7 +53,7 @@ fs.writeFileSync('playwright/.auth/passkey.json', JSON.stringify(credential));
 // later test: seed the captured passkey so the app starts already enrolled.
 const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
 const context = await browser.newContext();
-await context.credentials.create(credential);
+await context.credentials.create(credential.rpId, credential);
 await context.credentials.install();
 
 const page = await context.newPage();
@@ -106,14 +105,35 @@ To **import a known credential**, supply all four of `id`, `userHandle`, `privat
 
 Call [`method: Credentials.install`] before navigating to a page that uses WebAuthn.
 
-### param: Credentials.create.options
+### param: Credentials.create.rpId
 * since: v1.61
-- `options` <[Object]>
-  - `rpId` <[string]> Relying party id (typically the site's effective domain).
-  - `id` ?<[string]> Base64url-encoded credential id. Auto-generated if omitted.
-  - `userHandle` ?<[string]> Base64url-encoded user handle. Auto-generated if omitted.
-  - `privateKey` ?<[string]> Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted.
-  - `publicKey` ?<[string]> Base64url-encoded SPKI (DER) public key. Auto-generated if omitted.
+- `rpId` <[string]>
+
+Relying party id (typically the site's effective domain).
+
+### option: Credentials.create.id
+* since: v1.61
+- `id` <[string]>
+
+Base64url-encoded credential id. Auto-generated if omitted.
+
+### option: Credentials.create.userHandle
+* since: v1.61
+- `userHandle` <[string]>
+
+Base64url-encoded user handle. Auto-generated if omitted.
+
+### option: Credentials.create.privateKey
+* since: v1.61
+- `privateKey` <[string]>
+
+Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted.
+
+### option: Credentials.create.publicKey
+* since: v1.61
+- `publicKey` <[string]>
+
+Base64url-encoded SPKI (DER) public key. Auto-generated if omitted.
 
 ## async method: Credentials.delete
 * since: v1.61

docs/src/auth.md

@@ -416,8 +416,7 @@ export * from '@playwright/test';
 export const test = baseTest.extend({
   context: async ({ context }, use) => {
     // A passkey your backend provisioned for the test user.
-    await context.credentials.create({
-      rpId: 'example.com',
+    await context.credentials.create('example.com', {
       id: process.env.PASSKEY_ID,
       userHandle: process.env.PASSKEY_USER_HANDLE,
       privateKey: process.env.PASSKEY_PRIVATE_KEY,
@@ -457,7 +456,7 @@ export * from '@playwright/test';
 export const test = baseTest.extend({
   context: async ({ context }, use) => {
     const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
-    await context.credentials.create(credential);
+    await context.credentials.create(credential.rpId, credential);
     await context.credentials.install();
     await use(context);
   },

packages/playwright-client/types/types.d.ts

@@ -18820,8 +18820,7 @@ export interface Coverage {
  * const context = await browser.newContext();
  *
  * // A passkey your backend already provisioned for a test user.
- * await context.credentials.create({
- *   rpId: 'example.com',
+ * await context.credentials.create('example.com', {
  *   id: knownCredentialId, // base64url
  *   userHandle: knownUserHandle, // base64url
  *   privateKey: knownPrivateKey, // base64url PKCS#8 (DER)
@@ -18854,7 +18853,7 @@ export interface Coverage {
  * // later test: seed the captured passkey so the app starts already enrolled.
  * const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
  * const context = await browser.newContext();
- * await context.credentials.create(credential);
+ * await context.credentials.create(credential.rpId, credential);
  * await context.credentials.install();
  *
  * const page = await context.newPage();
@@ -18877,9 +18876,10 @@ export interface Credentials {
    *
    * Call [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install) before
    * navigating to a page that uses WebAuthn.
+   * @param rpId Relying party id (typically the site's effective domain).
    * @param options
    */
-  create(options: {
+  create(rpId: string, options?: {
     /**
      * Base64url-encoded credential id. Auto-generated if omitted.
      */
@@ -18895,11 +18895,6 @@ export interface Credentials {
      */
     publicKey?: string;
 
-    /**
-     * Relying party id (typically the site's effective domain).
-     */
-    rpId: string;
-
     /**
      * Base64url-encoded user handle. Auto-generated if omitted.
      */
@@ -18933,22 +18928,22 @@ export interface Credentials {
 
   /**
    * Removes a credential from the authenticator by its id. Works for any credential currently held — both those seeded
-   * with [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) and those
-   * the page registered itself by calling `navigator.credentials.create()`.
+   * with [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create)
+   * and those the page registered itself by calling `navigator.credentials.create()`.
    * @param id Base64url-encoded credential id.
    */
   delete(id: string): Promise<void>;
 
   /**
    * Returns every credential currently held by the authenticator, optionally filtered by `rpId` or `id`. This includes
    * both credentials seeded with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) and credentials
-   * the page registered itself by calling `navigator.credentials.create()`.
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) and
+   * credentials the page registered itself by calling `navigator.credentials.create()`.
    *
    * Each returned credential includes its `privateKey` and `publicKey`, so a passkey the app just registered can be
    * saved and re-seeded into a later test with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) — see the
-   * second example in the class overview.
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) — see
+   * the second example in the class overview.
    * @param options
    */
   get(options?: {
@@ -18980,7 +18975,7 @@ export interface Credentials {
    *
    * Required: until `install()` is called, no interception is in place and the page sees the platform's native (or
    * absent) WebAuthn behaviour. Seeding credentials with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) without
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) without
    * `install()` populates the authenticator, but the page will never see those credentials.
    */
   install(): Promise<void>;

packages/playwright-core/src/client/credentials.ts

@@ -29,8 +29,8 @@ export class Credentials implements api.Credentials {
     await this._browserContext._channel.credentialsInstall({});
   }
 
-  async create(options: channels.BrowserContextCredentialsCreateParams): Promise<channels.VirtualCredential> {
-    const { credential } = await this._browserContext._channel.credentialsCreate(options);
+  async create(rpId: string, options: Omit<channels.BrowserContextCredentialsCreateParams, 'rpId'> = {}): Promise<channels.VirtualCredential> {
+    const { credential } = await this._browserContext._channel.credentialsCreate({ ...options, rpId });
     return credential;
   }
 

packages/playwright-core/types/types.d.ts

@@ -18820,8 +18820,7 @@ export interface Coverage {
  * const context = await browser.newContext();
  *
  * // A passkey your backend already provisioned for a test user.
- * await context.credentials.create({
- *   rpId: 'example.com',
+ * await context.credentials.create('example.com', {
  *   id: knownCredentialId, // base64url
  *   userHandle: knownUserHandle, // base64url
  *   privateKey: knownPrivateKey, // base64url PKCS#8 (DER)
@@ -18854,7 +18853,7 @@ export interface Coverage {
  * // later test: seed the captured passkey so the app starts already enrolled.
  * const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
  * const context = await browser.newContext();
- * await context.credentials.create(credential);
+ * await context.credentials.create(credential.rpId, credential);
  * await context.credentials.install();
  *
  * const page = await context.newPage();
@@ -18877,9 +18876,10 @@ export interface Credentials {
    *
    * Call [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install) before
    * navigating to a page that uses WebAuthn.
+   * @param rpId Relying party id (typically the site's effective domain).
    * @param options
    */
-  create(options: {
+  create(rpId: string, options?: {
     /**
      * Base64url-encoded credential id. Auto-generated if omitted.
      */
@@ -18895,11 +18895,6 @@ export interface Credentials {
      */
     publicKey?: string;
 
-    /**
-     * Relying party id (typically the site's effective domain).
-     */
-    rpId: string;
-
     /**
      * Base64url-encoded user handle. Auto-generated if omitted.
      */
@@ -18933,22 +18928,22 @@ export interface Credentials {
 
   /**
    * Removes a credential from the authenticator by its id. Works for any credential currently held — both those seeded
-   * with [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) and those
-   * the page registered itself by calling `navigator.credentials.create()`.
+   * with [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create)
+   * and those the page registered itself by calling `navigator.credentials.create()`.
    * @param id Base64url-encoded credential id.
    */
   delete(id: string): Promise<void>;
 
   /**
    * Returns every credential currently held by the authenticator, optionally filtered by `rpId` or `id`. This includes
    * both credentials seeded with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) and credentials
-   * the page registered itself by calling `navigator.credentials.create()`.
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) and
+   * credentials the page registered itself by calling `navigator.credentials.create()`.
    *
    * Each returned credential includes its `privateKey` and `publicKey`, so a passkey the app just registered can be
    * saved and re-seeded into a later test with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) — see the
-   * second example in the class overview.
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) — see
+   * the second example in the class overview.
    * @param options
    */
   get(options?: {
@@ -18980,7 +18975,7 @@ export interface Credentials {
    *
    * Required: until `install()` is called, no interception is in place and the page sees the platform's native (or
    * absent) WebAuthn behaviour. Seeding credentials with
-   * [credentials.create(options)](https://playwright.dev/docs/api/class-credentials#credentials-create) without
+   * [credentials.create(rpId[, options])](https://playwright.dev/docs/api/class-credentials#credentials-create) without
    * `install()` populates the authenticator, but the page will never see those credentials.
    */
   install(): Promise<void>;

tests/library/browsercontext-webauthn.spec.ts

@@ -19,7 +19,7 @@ import { browserTest as it, expect } from '../config/browserTest';
 it('should not intercept navigator.credentials without install()', async ({ contextFactory, server }) => {
   const context = await contextFactory();
   // Seed a credential, but do not install the interceptor.
-  await context.credentials.create({ rpId: server.HOSTNAME });
+  await context.credentials.create(server.HOSTNAME);
   const page = await context.newPage();
   await page.goto(server.EMPTY_PAGE);
 
@@ -31,11 +31,11 @@ it('should seed a known credential and authenticate', async ({ contextFactory, s
   // This is the easiest way to create credentials. In practice, this
   // probably comes from environment.
   const source = await contextFactory();
-  const known = await source.credentials.create({ rpId: server.HOSTNAME });
+  const known = await source.credentials.create(server.HOSTNAME);
 
   // A fresh context imports the known credential and signs in with it.
   const context = await contextFactory();
-  await context.credentials.create(known);
+  await context.credentials.create(known.rpId, known);
   await context.credentials.install();
   const page = await context.newPage();
   await page.goto(server.EMPTY_PAGE);
@@ -139,7 +139,7 @@ it('should capture a page-created credential and reuse it in another context', a
 
   // Reuse the captured passkey in a fresh context and sign in with it.
   const context = await contextFactory();
-  await context.credentials.create(captured);
+  await context.credentials.create(captured.rpId, captured);
   await context.credentials.install();
   const page = await context.newPage();
   await page.goto(server.EMPTY_PAGE);