@interop/did-method-webvh 3.2.0 → 3.3.0

package/dist/method_versions/method.v1.0.js

@@ -1,16 +1,36 @@
 import { documentStateIsValid, hashChainValid, newKeysAreInNextKeys, scidIsFromHash } from '../assertions.js';
-import { METHOD, PLACEHOLDER } from '../constants.js';
+import { CONTEXT_LINKED_VP, ERROR_TYPE_INVALID_DID, ERROR_TYPE_NOT_FOUND, METHOD, METHOD_PARAMETER_KEYS, METHOD_PROTOCOL_V1_0, PLACEHOLDER, SERVICE_TYPE_LINKED_VP, SERVICE_TYPE_RELATIVE_REF, ServiceFragment, } from '../constants.js';
 import { DidResolutionError } from '../interfaces.js';
-import { createDate, createDIDDoc, createSCID, deepClone, deriveHash, enrichAlsoKnownAs, findVerificationMethod, generateParallelDidWeb, getBaseUrl, parseCanonicalAddress, replaceCreateDidPlaceholders, replaceValueInObject, validateCreateDidDocument, } from '../utils.js';
+import { createNextVersionTime, parseUtcIso8601VersionTime, validateUtcIso8601NotInFuture, } from '../utils/iso8601-datetime.js';
+import { createDate, createDIDDoc, createSCID, deepClone, deriveHash, enrichAlsoKnownAs, findVerificationMethod, generateParallelDidWeb, getBaseUrl, parseCanonicalAddress, parseDidWebvhIdentifier, replaceCreateDidPlaceholders, replaceValueInObject, serviceFragmentExists, validateCreateDidDocument, validateMethodSpecificPathSegments, } from '../utils.js';
 import { countVerifiedWitnessApprovals, fetchWitnessProofs, validateWitnessParameter } from '../witness.js';
-const VERSION = '1.0';
-const PROTOCOL = `did:${METHOD}:${VERSION}`;
+const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
 const requireDidId = (id) => {
     if (!id) {
         throw new Error('DID document id is missing');
     }
     return id;
 };
+const parseAndValidateVersionId = (versionId, expectedVersionNumber) => {
+    const firstDashIndex = versionId.indexOf('-');
+    const lastDashIndex = versionId.lastIndexOf('-');
+    if (firstDashIndex === -1 || firstDashIndex !== lastDashIndex) {
+        throw new Error(`versionId '${versionId}' must contain exactly one '-' separator`);
+    }
+    const version = versionId.slice(0, firstDashIndex);
+    const entryHash = versionId.slice(firstDashIndex + 1);
+    if (!/^\d+$/.test(version)) {
+        throw new Error(`versionId '${versionId}' must have a numeric version prefix`);
+    }
+    if (entryHash.length === 0) {
+        throw new Error(`versionId '${versionId}' must have a non-empty hash component`);
+    }
+    const versionNumber = Number(version);
+    if (versionNumber !== expectedVersionNumber) {
+        throw new Error(`version '${version}' in log doesn't match expected '${expectedVersionNumber}'.`);
+    }
+    return { version, versionNumber, entryHash };
+};
 export const createDID = async (options) => {
     if (!options.updateKeys) {
         throw new Error('Update keys not supplied');
@@ -26,8 +46,12 @@ export const createDID = async (options) => {
     const parsed = parseCanonicalAddress(addressInput);
     const didDomainComponent = parsed.didDomainComponent;
     const allPaths = [...(parsed.paths || []), ...(options.paths || [])];
+    validateMethodSpecificPathSegments(allPaths, 'createDID path segments');
     const path = allPaths.length > 0 ? allPaths.join(':') : undefined;
     const controller = `did:${METHOD}:${PLACEHOLDER}:${didDomainComponent}${path ? `:${path}` : ''}`;
+    if (options.created) {
+        validateUtcIso8601NotInFuture(options.created, 'createDID created');
+    }
     const createdDate = createDate(options.created);
     // Safety guard: Strip secret keys from verification methods before creating DID document
     const safeVerificationMethods = options.verificationMethods?.map((vm) => {
@@ -72,7 +96,7 @@ export const createDID = async (options) => {
         versionId: PLACEHOLDER,
         versionTime: createdDate,
         parameters: {
-            method: PROTOCOL,
+            method: METHOD_PROTOCOL_V1_0,
             ...params,
         },
         state: doc,
@@ -103,6 +127,9 @@ export const createDID = async (options) => {
         throw new Error(`version ${prelimEntry.versionId} is invalid.`);
     }
     const didId = requireDidId(prelimEntry.state.id);
+    if (didId !== didWithScid) {
+        throw new Error(`Created DID document id must match expected DID '${didWithScid}', got '${didId}'`);
+    }
     const webDoc = options.alsoKnownAsWeb ? generateParallelDidWeb(didId, prelimEntry.state) : undefined;
     return {
         did: didId,
@@ -123,14 +150,19 @@ export const resolveDIDFromLog = async (log, options = {}) => {
         throw new Error('Cannot specify both verificationMethod and version number/id');
     }
     const resolutionLog = log.map((l) => deepClone(l));
+    if (resolutionLog.length === 0) {
+        throw new Error(`Log identity binding check failed: no entries to process`);
+    }
     const protocol = resolutionLog[0]?.parameters?.method;
-    if (protocol !== PROTOCOL) {
+    if (protocol !== METHOD_PROTOCOL_V1_0) {
         throw new Error(`'${protocol}' is not a supported method version.`);
     }
     let did = '';
     let doc = null;
     let resolvedDoc = null;
+    let resolvedDid = null;
     let lastValidDoc = null;
+    let lastValidDid = null;
     const meta = {
         versionId: '',
         created: '',
@@ -147,31 +179,41 @@ export const resolveDIDFromLog = async (log, options = {}) => {
     let resolvedMeta = null;
     let lastValidMeta = null;
     let i = 0;
+    const hasExplicitHistoricalSelector = options.versionNumber !== undefined ||
+        options.versionId !== undefined ||
+        options.versionTime !== undefined ||
+        options.verificationMethod !== undefined;
+    let didIdMatchCount = 0;
     let host = '';
+    let previousVersionTime;
     const requiredWitnessChecks = [];
-    // Fast resolution is opt-in; full verification is the default conformant path.
-    const fastResolve = options.fastResolve ?? false;
-    const isFirstEntry = (idx) => idx === 0;
-    const isLastFewEntries = (idx) => idx >= resolutionLog.length - 10; // Verify last 10 entries
-    const shouldVerifyEntry = (idx) => !fastResolve || isFirstEntry(idx) || isLastFewEntries(idx);
+    let witnessThresholdFailure = false;
     try {
         while (i < resolutionLog.length) {
             const { versionId, versionTime, parameters, state, proof } = resolutionLog[i];
-            const [version, entryHash] = versionId.split('-');
+            const { version, versionNumber, entryHash } = parseAndValidateVersionId(versionId, i + 1);
             const previousWitness = meta.witness ? deepClone(meta.witness) : undefined;
-            if (parseInt(version, 10) !== i + 1) {
-                throw new Error(`version '${version}' in log doesn't match expected '${i + 1}'.`);
-            }
             meta.versionId = versionId;
-            if (versionTime) {
-                // TODO check timestamps make sense
+            if (!versionTime) {
+                throw new Error(`version '${version}' is missing versionTime`);
+            }
+            const currentVersionTime = parseUtcIso8601VersionTime(versionTime, `version '${version}' versionTime`);
+            if (previousVersionTime && currentVersionTime.getTime() <= previousVersionTime.getTime()) {
+                throw new Error(`versionTime for version '${version}' must be greater than previous entry time`);
             }
+            // Check against resolver's current time for each entry per spec normative language
+            const maxAllowedFutureTime = Date.now() + MAX_FUTURE_SKEW_MS;
+            if (currentVersionTime.getTime() > maxAllowedFutureTime) {
+                throw new Error(`versionTime for version '${version}' must not be more than 5 minutes in the future`);
+            }
+            previousVersionTime = currentVersionTime;
             meta.updated = versionTime;
             let newDoc = state;
+            const parsedStateDid = parseDidWebvhIdentifier(requireDidId(newDoc.id), `version '${version}' state.id`);
             if (version === '1') {
                 meta.created = versionTime;
                 newDoc = state;
-                host = newDoc.id.split(':').at(-1);
+                host = parsedStateDid.locationKey;
                 meta.scid = parameters.scid;
                 if (options.scid && options.scid !== meta.scid) {
                     throw new Error(`SCID in DID '${options.scid}' does not match SCID in log '${meta.scid}'`);
@@ -182,81 +224,101 @@ export const resolveDIDFromLog = async (log, options = {}) => {
                 meta.prerotation = meta.nextKeyHashes.length > 0;
                 meta.witness = parameters.witness || meta.witness;
                 meta.watchers = parameters.watchers ?? null;
-                if (shouldVerifyEntry(i)) {
-                    // Optimized: Use efficient object manipulation instead of JSON stringify/parse
-                    const logEntry = {
-                        versionId: PLACEHOLDER,
-                        versionTime: meta.created,
-                        parameters: replaceValueInObject(parameters, meta.scid, PLACEHOLDER),
-                        state: replaceValueInObject(newDoc, meta.scid, PLACEHOLDER),
-                    };
-                    const logEntryHash = await deriveHash(logEntry);
-                    meta.previousLogEntryHash = logEntryHash;
-                    if (!(await scidIsFromHash(meta.scid, logEntryHash))) {
-                        throw new Error(`SCID '${meta.scid}' not derived from logEntryHash '${logEntryHash}'`);
-                    }
-                    // Optimized: Direct object manipulation instead of JSON stringify/parse
-                    const prelimEntry = replaceValueInObject(logEntry, PLACEHOLDER, meta.scid);
-                    const logEntryHash2 = await deriveHash(prelimEntry);
-                    const verified = await documentStateIsValid({ ...prelimEntry, versionId: `1-${logEntryHash2}`, proof }, meta.updateKeys, meta.witness, false, options.verifier);
-                    if (!verified) {
-                        throw new Error(`version ${meta.versionId} failed verification of the proof.`);
-                    }
+                // Optimized: Use efficient object manipulation instead of JSON stringify/parse
+                const logEntry = {
+                    versionId: PLACEHOLDER,
+                    versionTime: meta.created,
+                    parameters: replaceValueInObject(parameters, meta.scid, PLACEHOLDER),
+                    state: replaceValueInObject(newDoc, meta.scid, PLACEHOLDER),
+                };
+                const logEntryHash = await deriveHash(logEntry);
+                meta.previousLogEntryHash = logEntryHash;
+                if (!(await scidIsFromHash(meta.scid, logEntryHash))) {
+                    throw new Error(`SCID '${meta.scid}' not derived from logEntryHash '${logEntryHash}'`);
+                }
+                if (parsedStateDid.scid !== meta.scid) {
+                    throw new Error(`SCID in state.id '${parsedStateDid.scid}' does not match SCID in log '${meta.scid}'`);
+                }
+                // Optimized: Direct object manipulation instead of JSON stringify/parse
+                const prelimEntry = replaceValueInObject(logEntry, PLACEHOLDER, meta.scid);
+                const logEntryHash2 = await deriveHash(prelimEntry);
+                const verified = await documentStateIsValid({ ...prelimEntry, versionId: `1-${logEntryHash2}`, proof }, meta.updateKeys, meta.witness, false, options.verifier);
+                if (!verified) {
+                    throw new Error(`version ${meta.versionId} failed verification of the proof.`);
                 }
             }
             else {
                 // version number > 1
-                const newHost = newDoc.id.split(':').at(-1);
-                if (!meta.portable && newHost !== host) {
+                // Validate method parameter: must not be present or must equal the supported method
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.method)) {
+                    const entryMethod = parameters.method;
+                    if (entryMethod !== METHOD_PROTOCOL_V1_0) {
+                        throw new Error(`version '${version}' has unsupported or downgraded method '${entryMethod}'; ` +
+                            `expected '${METHOD_PROTOCOL_V1_0}'`);
+                    }
+                }
+                // scid MUST NOT appear in later entries
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.scid)) {
+                    throw new Error(`version '${version}' must not contain SCID parameter`);
+                }
+                // portable: true cannot be introduced after the first entry — it can only remain
+                // true if it was already enabled in the first entry
+                if (parameters.portable === true && !meta.portable) {
+                    throw new Error(`version '${version}' cannot set portable: true; portability can only be enabled in the first entry`);
+                }
+                // Setting portable: false in a later entry permanently locks portability off
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.portable) && parameters.portable === false) {
+                    meta.portable = false;
+                }
+                if (parsedStateDid.scid !== meta.scid) {
+                    throw new Error(`SCID in state.id '${parsedStateDid.scid}' does not match SCID in log '${meta.scid}'`);
+                }
+                const newLocation = parsedStateDid.locationKey;
+                if (!meta.portable && newLocation !== host) {
                     throw new Error('Cannot move DID: portability is disabled');
                 }
-                else if (newHost !== host) {
-                    host = newHost;
+                else if (newLocation !== host) {
+                    host = newLocation;
                 }
-                // Hash chain — ALWAYS runs (cheap), even in fast-resolve
+                // Hash chain
                 const { proof: _proof, ...entryWithoutProof } = resolutionLog[i];
                 const recomputedHash = await deriveHash({ ...entryWithoutProof, versionId: resolutionLog[i - 1].versionId });
                 if (!hashChainValid(recomputedHash, entryHash)) {
                     throw new Error(`Hash chain broken at '${meta.versionId}'`);
                 }
-                if (shouldVerifyEntry(i)) {
-                    // Signature verification — expensive, skipped for middle entries in fast-resolve
-                    const keys = meta.prerotation ? parameters.updateKeys : meta.updateKeys;
-                    const verified = await documentStateIsValid(resolutionLog[i], keys, meta.witness, false, options.verifier);
-                    if (!verified) {
-                        throw new Error(`version ${meta.versionId} failed verification of the proof.`);
-                    }
-                    if (meta.prerotation) {
-                        await newKeysAreInNextKeys(parameters.updateKeys ?? [], meta.nextKeyHashes ?? []);
-                    }
+                // Signature verification
+                const keys = meta.prerotation ? parameters.updateKeys : meta.updateKeys;
+                const verified = await documentStateIsValid(resolutionLog[i], keys, meta.witness, false, options.verifier);
+                if (!verified) {
+                    throw new Error(`version ${meta.versionId} failed verification of the proof.`);
                 }
-                if (parameters.updateKeys) {
-                    meta.updateKeys = parameters.updateKeys;
+                if (meta.prerotation) {
+                    await newKeysAreInNextKeys(parameters.updateKeys ?? [], meta.nextKeyHashes ?? []);
+                }
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.updateKeys)) {
+                    meta.updateKeys = parameters.updateKeys ?? [];
                 }
                 if (parameters.deactivated === true) {
                     meta.deactivated = true;
                 }
-                if (parameters.nextKeyHashes && parameters.nextKeyHashes.length > 0) {
-                    meta.nextKeyHashes = parameters.nextKeyHashes;
-                    meta.prerotation = true;
-                }
-                else {
-                    meta.nextKeyHashes = [];
-                    meta.prerotation = false;
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.nextKeyHashes)) {
+                    meta.nextKeyHashes = parameters.nextKeyHashes ?? [];
+                    meta.prerotation = meta.nextKeyHashes.length > 0;
                 }
-                if ('witness' in parameters) {
+                const legacyParameters = parameters;
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.witness)) {
                     meta.witness = parameters.witness;
                 }
-                else if (parameters.witnesses) {
+                else if (legacyParameters.witnesses) {
                     meta.witness = {
-                        witnesses: parameters.witnesses,
-                        threshold: parameters.witnessThreshold || parameters.witnesses.length,
+                        witnesses: legacyParameters.witnesses,
+                        threshold: legacyParameters.witnessThreshold || legacyParameters.witnesses.length,
                     };
                 }
                 if (meta.witness?.witnesses?.length) {
                     validateWitnessParameter(meta.witness);
                 }
-                if ('watchers' in parameters) {
+                if (Object.hasOwn(parameters, METHOD_PARAMETER_KEYS.watchers)) {
                     meta.watchers = parameters.watchers ?? null;
                 }
             }
@@ -264,64 +326,55 @@ export const resolveDIDFromLog = async (log, options = {}) => {
             if (requiredWitness) {
                 requiredWitnessChecks.push({
                     targetVersionId: meta.versionId,
-                    targetVersionNumber: parseInt(version, 10),
+                    targetVersionNumber: versionNumber,
                     witness: requiredWitness,
                 });
             }
             // Optimized: Use efficient cloning instead of clone() function
             doc = deepClone(newDoc);
-            did = doc.id;
-            // Only add default services for entries we need to process
-            if (shouldVerifyEntry(i) || i === resolutionLog.length - 1) {
-                // Add default services if they don't exist
-                doc.service = Array.isArray(doc.service) ? doc.service : [];
-                const baseUrl = getBaseUrl(did);
-                if (!doc.service.some((s) => s.id === '#files')) {
-                    doc.service.push({
-                        id: '#files',
-                        type: 'relativeRef',
-                        serviceEndpoint: baseUrl,
-                    });
-                }
-                if (!doc.service.some((s) => s.id === '#whois')) {
-                    doc.service.push({
-                        '@context': 'https://identity.foundation/linked-vp/contexts/v1',
-                        id: '#whois',
-                        type: 'LinkedVerifiablePresentation',
-                        serviceEndpoint: `${baseUrl}/whois.vp`,
-                    });
-                }
+            did = requireDidId(doc.id);
+            if (options.requestedDid && did === options.requestedDid) {
+                didIdMatchCount++;
             }
-            if (options.verificationMethod && findVerificationMethod(doc, options.verificationMethod)) {
-                if (!resolvedDoc) {
-                    resolvedDoc = deepClone(doc);
-                    resolvedMeta = { ...meta };
-                }
+            // Add default services if they don't exist
+            doc.service = Array.isArray(doc.service) ? doc.service : [];
+            const baseUrl = getBaseUrl(did);
+            if (!serviceFragmentExists(doc.service, ServiceFragment.Files, did)) {
+                doc.service.push({
+                    id: '#files',
+                    type: SERVICE_TYPE_RELATIVE_REF,
+                    serviceEndpoint: baseUrl,
+                });
             }
-            if (options.versionNumber === parseInt(version, 10) || options.versionId === meta.versionId) {
-                if (!resolvedDoc) {
-                    resolvedDoc = deepClone(doc);
-                    resolvedMeta = { ...meta };
-                }
+            if (!serviceFragmentExists(doc.service, ServiceFragment.Whois, did)) {
+                doc.service.push({
+                    '@context': CONTEXT_LINKED_VP,
+                    id: '#whois',
+                    type: SERVICE_TYPE_LINKED_VP,
+                    serviceEndpoint: `${baseUrl}/whois.vp`,
+                });
             }
-            if (options.versionTime && options.versionTime > new Date(meta.updated)) {
-                if (resolutionLog[i + 1] && options.versionTime < new Date(resolutionLog[i + 1].versionTime)) {
-                    if (!resolvedDoc) {
-                        resolvedDoc = deepClone(doc);
-                        resolvedMeta = { ...meta };
-                    }
-                }
-                else if (!resolutionLog[i + 1]) {
-                    if (!resolvedDoc) {
-                        resolvedDoc = deepClone(doc);
-                        resolvedMeta = { ...meta };
-                    }
-                }
+            // Latch the first entry matching the requested selector as the resolved result.
+            let matchesSelector = (!!options.verificationMethod && !!findVerificationMethod(doc, options.verificationMethod)) ||
+                options.versionNumber === versionNumber ||
+                options.versionId === meta.versionId;
+            if (!matchesSelector && options.versionTime && options.versionTime > new Date(meta.updated)) {
+                const nextEntry = resolutionLog[i + 1];
+                matchesSelector = !nextEntry || options.versionTime < new Date(nextEntry.versionTime);
+            }
+            if (matchesSelector && !resolvedDoc) {
+                resolvedDoc = deepClone(doc);
+                resolvedDid = did;
+                resolvedMeta = { ...meta };
             }
             lastValidDoc = deepClone(doc);
+            lastValidDid = did;
             lastValidMeta = { ...meta };
             i++;
         }
+        if (options.requestedDid && didIdMatchCount === 0) {
+            throw new Error(`Requested DID '${options.requestedDid}' does not match state.id in any valid log version`);
+        }
         if (requiredWitnessChecks.length > 0) {
             if (!options.witnessProofs) {
                 options.witnessProofs = await fetchWitnessProofs(did);
@@ -335,6 +388,7 @@ export const resolveDIDFromLog = async (log, options = {}) => {
                 const approvals = await countVerifiedWitnessApprovals(resolutionLog[check.targetVersionNumber - 1], candidateProofs, check.witness, options.verifier);
                 const threshold = parseInt((check.witness.threshold ?? 0).toString(), 10);
                 if (approvals < threshold) {
+                    witnessThresholdFailure = true;
                     throw new Error(`Witness threshold not met for version ${check.targetVersionId}: got ${approvals}, need ${check.witness.threshold}`);
                 }
             }
@@ -344,25 +398,59 @@ export const resolveDIDFromLog = async (log, options = {}) => {
         if (!resolvedDoc) {
             throw e;
         }
-        if (resolvedMeta) {
+        if (resolvedMeta && (!hasExplicitHistoricalSelector || witnessThresholdFailure)) {
             const message = e instanceof Error ? e.message : String(e);
             resolvedMeta.error = DidResolutionError.InvalidDid;
             resolvedMeta.problemDetails = {
-                type: 'https://w3id.org/security#INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID',
+                type: ERROR_TYPE_INVALID_DID,
                 title: 'The resolved DID is invalid.',
                 detail: message,
             };
         }
     }
     if (!resolvedDoc) {
-        resolvedDoc = lastValidDoc;
+        if (hasExplicitHistoricalSelector) {
+            if (!lastValidMeta || !lastValidDid) {
+                throw new Error('DID resolution failed: No valid result available for explicit selector');
+            }
+            return {
+                did: lastValidDid,
+                doc: null,
+                meta: {
+                    ...lastValidMeta,
+                    error: DidResolutionError.NotFound,
+                    problemDetails: {
+                        type: ERROR_TYPE_NOT_FOUND,
+                        title: 'The requested DID version was not found.',
+                        detail: 'The supplied explicit version selector did not match any entry in the DID log.',
+                    },
+                },
+            };
+        }
         resolvedMeta = lastValidMeta;
+        resolvedDid = lastValidDid;
+        if (resolvedMeta && !(resolvedMeta.deactivated && !hasExplicitHistoricalSelector)) {
+            resolvedDoc = lastValidDoc;
+        }
     }
     if (!resolvedMeta) {
         throw new Error('DID resolution failed: No valid metadata found');
     }
+    if (!resolvedDid) {
+        throw new Error('DID resolution failed: No valid identifier found');
+    }
+    if (resolvedMeta.deactivated && !hasExplicitHistoricalSelector) {
+        return {
+            did: resolvedDid,
+            doc: null,
+            meta: resolvedMeta,
+        };
+    }
+    if (!resolvedDoc) {
+        throw new Error('DID resolution failed: No valid document found');
+    }
     return {
-        did,
+        did: resolvedDid,
         doc: resolvedDoc,
         meta: resolvedMeta,
     };
@@ -370,14 +458,25 @@ export const resolveDIDFromLog = async (log, options = {}) => {
 export const updateDID = async (options) => {
     const log = options.log;
     const lastEntry = log[log.length - 1];
+    const lastEntryDid = requireDidId(lastEntry.state.id);
+    const parsedLastEntryDid = parseDidWebvhIdentifier(lastEntryDid, 'last entry state.id');
     const lastMeta = (await resolveDIDFromLog(log, { verifier: options.verifier, witnessProofs: options.witnessProofs }))
         .meta;
+    const currentUpdateKeys = options.updateKeys;
     if (lastMeta.deactivated) {
         throw new Error('Cannot update deactivated DID');
     }
+    if (lastMeta.prerotation && currentUpdateKeys === undefined) {
+        throw new Error('updateKeys must be provided while pre-rotation is active');
+    }
     const versionNumber = log.length + 1;
-    const createdDate = createDate(options.updated);
+    // Validate user-provided timestamp with skew tolerance before creating the versionTime
+    if (options.updated) {
+        validateUtcIso8601NotInFuture(options.updated, 'updateDID updated', MAX_FUTURE_SKEW_MS);
+    }
+    const createdDate = createNextVersionTime(lastMeta.updated, options.updated, createDate);
     const watchersValue = options.watchers !== undefined ? options.watchers : lastMeta.watchers;
+    const resolvedNextKeyHashes = options.nextKeyHashes ?? lastMeta.nextKeyHashes ?? [];
     const witnessInput = options.witness;
     const witness = witnessInput?.witnesses?.length
         ? {
@@ -385,15 +484,24 @@ export const updateDID = async (options) => {
             threshold: witnessInput.threshold ?? 0,
         }
         : {};
+    if (options.portable === true) {
+        throw new Error('portable: true cannot be set in an update entry; portability can only be enabled in the first entry');
+    }
     const params = {
-        updateKeys: options.updateKeys ?? [],
-        nextKeyHashes: options.nextKeyHashes ?? [],
+        ...(options.updateKeys !== undefined || lastMeta.prerotation
+            ? { updateKeys: options.updateKeys ?? lastMeta.updateKeys }
+            : {}),
+        ...(options.nextKeyHashes !== undefined ? { nextKeyHashes: options.nextKeyHashes } : {}),
+        ...(options.portable === false ? { portable: false } : {}),
         witness,
         watchers: watchersValue ?? [],
     };
     if (params.witness?.witnesses?.length) {
         validateWitnessParameter(params.witness);
     }
+    if (lastMeta.prerotation) {
+        await newKeysAreInNextKeys(currentUpdateKeys ?? [], lastMeta.nextKeyHashes ?? []);
+    }
     // Safety guard: Strip secret keys from verification methods before creating DID document
     const safeVerificationMethods = options.verificationMethods?.map((vm) => {
         if (vm.secretKeyMultibase) {
@@ -403,26 +511,77 @@ export const updateDID = async (options) => {
         }
         return vm;
     });
-    const { doc } = await createDIDDoc({
+    // Determine the controller (the DID id) for this update. When a new location
+    // (address/domain) is supplied, rebuild the controller from that location while
+    // preserving the SCID, so a portable DID can actually move. The SCID is the
+    // stable part of the identifier; only the location component changes.
+    const requestedAddress = options.address || options.domain;
+    let controller;
+    let controllerPaths = parsedLastEntryDid.paths;
+    if (options.controller) {
+        controller = options.controller;
+    }
+    else if (requestedAddress) {
+        const parsedNewAddress = parseCanonicalAddress(requestedAddress);
+        // Paths: explicit options.paths (combined with any address-embedded paths) take
+        // precedence; otherwise use address-embedded paths; otherwise inherit the prior
+        // paths so re-passing a bare domain on a pathed DID doesn't silently drop them.
+        const addressPaths = parsedNewAddress.paths || [];
+        const newLocationPaths = options.paths !== undefined
+            ? [...addressPaths, ...options.paths]
+            : addressPaths.length
+                ? addressPaths
+                : (parsedLastEntryDid.paths ?? []);
+        const newLocationKey = newLocationPaths.length
+            ? `${parsedNewAddress.didDomainComponent}:${newLocationPaths.join(':')}`
+            : parsedNewAddress.didDomainComponent;
+        controller = `did:${METHOD}:${parsedLastEntryDid.scid}:${newLocationKey}`;
+        controllerPaths = newLocationPaths.length ? newLocationPaths : undefined;
+        if (controller !== lastEntryDid && !lastMeta.portable) {
+            throw new Error('Cannot move DID: portability is disabled');
+        }
+    }
+    else {
+        controller = lastEntryDid;
+    }
+    const { doc: normalizedUpdateDoc } = await createDIDDoc({
         ...options,
-        controller: options.controller || lastEntry.state.id || '',
+        controller,
         context: options.context || lastEntry.state['@context'],
-        domain: options.domain ?? lastEntry.state.id?.split(':').at(-1) ?? '',
+        domain: requestedAddress ?? parsedLastEntryDid.didDomainComponent,
+        paths: controllerPaths,
         updateKeys: options.updateKeys ?? [],
         verificationMethods: safeVerificationMethods ?? [],
     });
-    // Add services if provided
-    if (options.services && options.services.length > 0) {
+    // Carry the prior DID document forward and selectively overlay only the fields
+    // this update actually supplies, so a sparse updateDID() preserves prior state.
+    const doc = deepClone(lastEntry.state);
+    doc['@context'] = normalizedUpdateDoc['@context'];
+    doc.id = normalizedUpdateDoc.id;
+    doc.controller = normalizedUpdateDoc.controller;
+    if (safeVerificationMethods !== undefined) {
+        doc.verificationMethod = normalizedUpdateDoc.verificationMethod;
+        doc.authentication = normalizedUpdateDoc.authentication;
+        doc.assertionMethod = normalizedUpdateDoc.assertionMethod;
+        doc.keyAgreement = normalizedUpdateDoc.keyAgreement;
+        doc.capabilityDelegation = normalizedUpdateDoc.capabilityDelegation;
+        doc.capabilityInvocation = normalizedUpdateDoc.capabilityInvocation;
+    }
+    if (options.services !== undefined) {
         doc.service = options.services;
     }
-    // Add assertionMethod if provided
-    if (options.assertionMethod) {
+    if (options.authentication !== undefined) {
+        doc.authentication = options.authentication;
+    }
+    if (options.assertionMethod !== undefined) {
         doc.assertionMethod = options.assertionMethod;
     }
-    // Add keyAgreement if provided
-    if (options.keyAgreement) {
+    if (options.keyAgreement !== undefined) {
         doc.keyAgreement = options.keyAgreement;
     }
+    if (options.alsoKnownAs !== undefined) {
+        doc.alsoKnownAs = options.alsoKnownAs;
+    }
     const logEntry = {
         versionId: lastEntry.versionId,
         versionTime: createdDate,
@@ -442,7 +601,10 @@ export const updateDID = async (options) => {
     const signedProof = await options.signer.sign({ document: prelimEntry, proof: proofTemplate });
     const allProofs = [{ ...proofTemplate, proofValue: signedProof.proofValue }];
     prelimEntry.proof = allProofs;
-    const keysToVerify = lastMeta.prerotation ? params.updateKeys : lastMeta.updateKeys;
+    const keysToVerify = lastMeta.prerotation ? currentUpdateKeys : lastMeta.updateKeys;
+    if (!keysToVerify) {
+        throw new Error('updateKeys could not be determined for update verification');
+    }
     const verified = await documentStateIsValid(prelimEntry, keysToVerify, lastMeta.witness, true, options.verifier);
     if (!verified) {
         throw new Error(`version ${prelimEntry.versionId} is invalid.`);
@@ -451,7 +613,7 @@ export const updateDID = async (options) => {
         ...lastMeta,
         versionId: prelimEntry.versionId,
         updated: prelimEntry.versionTime,
-        prerotation: (params.nextKeyHashes?.length ?? 0) > 0,
+        prerotation: resolvedNextKeyHashes.length > 0,
         ...params,
     };
     const hasWebAlias = (prelimEntry.state.alsoKnownAs ?? []).some((alias) => alias.startsWith('did:web:'));
@@ -473,7 +635,7 @@ export const deactivateDID = async (options) => {
         throw new Error('DID already deactivated');
     }
     const versionNumber = log.length + 1;
-    const createdDate = createDate();
+    const createdDate = createNextVersionTime(lastMeta.updated, undefined, createDate);
     const params = {
         updateKeys: options.updateKeys ?? lastMeta.updateKeys,
         deactivated: true,
@@ -522,9 +684,10 @@ const getEntryWitnessParameter = (parameters) => {
         return parameters.witness ?? {};
     }
     if (parameters.witnesses) {
+        const legacyParameters = parameters;
         return {
-            witnesses: parameters.witnesses,
-            threshold: parameters.witnessThreshold || parameters.witnesses.length,
+            witnesses: legacyParameters.witnesses,
+            threshold: legacyParameters.witnessThreshold || legacyParameters.witnesses.length,
         };
     }
     return undefined;