docs: initial design proposal #14

jpower432 · 2022-11-03T13:07:35Z

High level design document or approach

Outline mock CLI
Provides background on Emporous concepts

TODO: Add high level architecture diagram.

Signed-off-by: Jennifer Power [email protected]

Signed-off-by: Jennifer Power <[email protected]>

Signed-off-by: Jennifer Power <[email protected]> docs: updates terminology and simplifies message Signed-off-by: Jennifer Power <[email protected]>

Signed-off-by: Jennifer Power <[email protected]>

jpower432 · 2023-01-13T22:03:15Z

@afflom @sabre1041 PTAL. The intention of this PR is to serve as a jumping off point and allow this to receive and and incorporate feedback. Please let me know if this would be preferred in a GitHub Discussion rather than a PR. This also might be be a good opportunity to come up with a proposal templates for updates. I could create a follow-on PR for a way to propose enhancements.

afflom

Great proposal. I dig it.

afflom · 2023-01-14T00:07:16Z

docs/design.md

+
+The purpose of the Emporous initiative is to create a scalable cross-content correlation framework that enhances the traceability of decentralized software artifacts.
+
+# Workflow and Critical User Journeys


Is it worth mentioning that the CLI is the reference implementation of the Emporous client library? (More than one way to interact with the Emporous client)

docs/design.md

afflom · 2023-01-14T00:50:35Z

docs/design.md

+On the client side, scoping queries to namespaces and repositories will be supported.
+## CLI/Client Libraries
+We have existing CLI and library code bases that manage single and linked artifacts. These will continue to be used to publish single artifacts and manage local storage. The CLI/libraries will be extended to interface with the proposed API changes.
+## Service Layer


Can we refer to this as an optional component? Or if a smart proxy is unavailable, will the client instantiate its own local "service layer"?

Even if the service is running on a user's machine it is still a running service and is still acting as a gateway between the client and registry. Is there a better way this could be conveyed in your opinion? I do not believe this functionality to be optional.

afflom · 2023-01-14T00:55:42Z

docs/design.md

+The attribute query endpoint can be used to automate building applications from existing artifacts. The endpoint will resolve an attribute query to an index manifest of matching descriptors that can be used for artifact publishing.
+
+To enable efficiency in this workflow, it would be best practice to only publish one component or file per artifact. 
+However, if an artifact is published with more than one file, the Emporous client will allow attribute filtering on individual artifacts.


I posit that an artifact is a blob + metadata. So, are we filtering a singular blob reference within a manifest that has multiple blob references?

The use of artifact throughout this document refers to an OCI artifact (there is an entry in the glossary for this). I would consider an entry for a blob + metadata to be a descriptor. Does this add any clarification?

afflom · 2023-01-14T00:59:28Z

docs/design.md

+To enable efficiency in this workflow, it would be best practice to only publish one component or file per artifact. 
+However, if an artifact is published with more than one file, the Emporous client will allow attribute filtering on individual artifacts.
+
+### Search Domains


I think that the concept of trusted domains is important to this section. From prior discussions, we have identified at least two zones present within a search domain: trusted and untrusted. A trusted zone is a registry that has been explicitly added to the user's search domain. The untrusted zone pertains to registries discovered via links published within the trusted zone.

If my use of the words trusted and untrusted are problematic, please disregard my words and use synonyms.

This might also be important to discovered pURL references.

I agree with adding something to convey the zones. I think we can use the word "discovered" for registries that have artifacts that satisfy the query, but are not specified by the user. Thoughts?

docs/design.md

afflom · 2023-01-14T01:05:47Z

docs/design.md

+}
+```
+
+### Signatures


I think that a signature being a searchable attribute is relevant to this discussion.

i.e. "A compromised key was used to sign content. Show all content signed by that key"

Co-authored-by: Alex Flom <[email protected]>

Signed-off-by: Jennifer Power <[email protected]>

…ce section Signed-off-by: Jennifer Power <[email protected]>

…ignatures Signed-off-by: Jennifer Power <[email protected]>

Signed-off-by: Jennifer Power <[email protected]>

usrbinkat · 2023-01-29T02:59:20Z

Recommend discussion on community call, added to 2023-02-01 agenda.

jpower432 · 2023-02-08T20:18:21Z

Converting to a draft, just to keep it from being merged into this repo until we find the correct place for it.

docs: initial design proposal

a1f0380

Signed-off-by: Jennifer Power <[email protected]>

jpower432 marked this pull request as draft November 3, 2022 18:49

jpower432 added 2 commits November 3, 2022 15:33

chore: updates core terminology (pending feedback)

199ac6d

Signed-off-by: Jennifer Power <[email protected]>

docs: adds updated design information

8c85395

Signed-off-by: Jennifer Power <[email protected]> docs: updates terminology and simplifies message Signed-off-by: Jennifer Power <[email protected]>

jpower432 force-pushed the docs/design branch from a561af2 to 8c85395 Compare January 13, 2023 21:45

fix: removes empty file

34d8790

Signed-off-by: Jennifer Power <[email protected]>

jpower432 changed the title ~~[WIP] docs: initial design proposal~~ docs: initial design proposal Jan 13, 2023

fix: adds grammar and spelling fixes

f93f8c8

Signed-off-by: Jennifer Power <[email protected]>

jpower432 marked this pull request as ready for review January 13, 2023 21:57

jpower432 requested review from afflom and sabre1041 January 13, 2023 21:58

afflom requested changes Jan 14, 2023

View reviewed changes

jpower432 and others added 6 commits January 13, 2023 21:20

Apply suggestions from code review

41b1d0b

Co-authored-by: Alex Flom <[email protected]>

chore: adds a linked reference for TOCTOU

8852ee8

Signed-off-by: Jennifer Power <[email protected]>

docs: incorportates feedback from code review on trusted content section

5817651

Signed-off-by: Jennifer Power <[email protected]>

docs: removes reference to single artifacts in CLI section

70b0269

Signed-off-by: Jennifer Power <[email protected]>

fix: fixes references to anchors in design document

a824dc1

Signed-off-by: Jennifer Power <[email protected]>

fix: removes broken deployment record anchor

0397d0a

Signed-off-by: Jennifer Power <[email protected]>

jpower432 requested review from d10n and sfxworks January 17, 2023 19:40

jpower432 added 3 commits January 18, 2023 15:10

docs: updates emporous-client to emporous in CLI mock up

7597413

Signed-off-by: Jennifer Power <[email protected]>

chore: adds information about recursive SLSA verification to provenan…

f4156c0

…ce section Signed-off-by: Jennifer Power <[email protected]>

docs: remove attribute implementation information for rework around s…

e7cd19d

…ignatures Signed-off-by: Jennifer Power <[email protected]>

usrbinkat approved these changes Jan 25, 2023

View reviewed changes

docs: refines some ambigous langauge around the referrers API

64dacd6

Signed-off-by: Jennifer Power <[email protected]>

jpower432 requested a review from a team as a code owner January 29, 2023 00:51

jpower432 marked this pull request as draft February 8, 2023 20:17


		The purpose of the Emporous initiative is to create a scalable cross-content correlation framework that enhances the traceability of decentralized software artifacts.

		# Workflow and Critical User Journeys

docs: initial design proposal #14

Are you sure you want to change the base?

docs: initial design proposal #14

Uh oh!

Conversation

jpower432 commented Nov 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jpower432 commented Jan 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

afflom left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpower432 Jan 14, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

usrbinkat commented Jan 29, 2023

Uh oh!

jpower432 commented Feb 8, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jpower432 commented Nov 3, 2022 •

edited

Loading

jpower432 commented Jan 13, 2023 •

edited

Loading

jpower432 Jan 14, 2023 •

edited

Loading