docs: readability edit of the w3-account spec

[olizilla]

Minor edits to

• improve the readability of the spec
• fix typos and wordos
• fix nesting of headers

License: MIT Signed-off-by: Oli Evans oli@protocol.ai

[olizilla]

@Gozala In the Email Validaition section, there is this line:

Authorization context, implying that this authorization MUST be considered valid by this recipient (aud matches this with).

and this example

{
  iss: "did:dns:web3.storage",
  aud: "did:mailto:alice@web.mail",
  att: [{
    with: "did:dns:web3.storage",
    can: "ucan/sign",
    nb: { as: "did:key:zAgent" }
  }],
  exp: null
  sig: "..."
}

is the "aud matches this with" assertion referring to a subsequent usage of this example ucan/sign as a proof... it's difficult to interpret it correctly on the first read as the immediate example doesn't show "aud matches this with".

see: https://github.com/web3-storage/specs/blob/79aec0efadff6a36fcb6e1d789cadd3fe3a83781/w3-account.md#L97

[Gozala]

is the "aud matches this with" assertion referring to a subsequent usage of this example ucan/sign as a proof... it's difficult to interpret it correctly on the first read as the immediate example doesn't show "aud matches this with".

Yeah I meant recipient of the invocation that uses authorization from the code snippet as a proof.

You are right, description is misleading especially since it follows code that does not show the whole picture.

[olizilla]

Ok, no worries, I will tweak in this PR to make that clearer

[olizilla]

I've added section headers for the capabilities introduced here and tried to give them each a short, neutral introduction, but I'm new here, so please do feel free to edit and add to them. Specifically access/delegate definitely needs more explaining, but i don't know which parts are normative and which bits are just to elucidate and example.

[Gozala]

Thanks @olizilla for the edits, it does reads much better now!